Re: [widgets] Editorial: 9x Processing

2009/6/10 Anne van Kesteren <annevk@opera.com>:
> I think this section should be more clearly (and cleanly) organized. It is very hard to tell which parts belong together. As such, "are written with more concern for clarity than efficiency" is somewhat ironic :-)
>

It's hard for me to address general comments like this. If there is a
specific part that is confusing, I will try my best to fix it. I can't
do anything if you say that the whole 20-odd page section is
incomprehensible. Other reviewers have not raised issues about the
ordering here. But, like I said, I am happy to make changes to make
things more clear if pointed to a precise issue.

> I'd suggest introducing new sections where that seems appropriate. E.g. "Rule for extracting file data from a file entry" clearly seems like it should be a section heading rather than just a boldened paragraph.
>

All Processing Rules are marked up as <h4>s. They are not boldened
paragraphs. However, to follow stylistic heading conventions, I have
capitalized the appropriate words. Does that help?

I had defined a processing rule within Step 1 ("Rule for Determining
if a Potential Zip Archive is a Zip Archive"), which I have moved to
the appropriate section.

> At the moment it has one section 9.1 and various sections starting with "Step" with no number. That should be sorted out.
>

Fixed.

> "Processing Rules" is probably also better renamed to indicate it is just a bunch of algorithms used in the section that follows. E.g. "common processing infrastructure" or something.
>

I left the title the same as "common processing infrastructure" seems
a bit abstract; however, I rewrote the definition of processing rules
to include your more precise  suggestion:

"This section defines various processing rules, which are a set of
common algorithms used by the steps for processing a widget package."

For the sake of the DoC, please confirm if you are satisfied with the
responses above.

Kind regards,
Marcos


-- 
Marcos Caceres
http://datadriven.com.au

Received on Monday, 29 June 2009 13:24:37 UTC