2009/6/10 Anne van Kesteren <[email protected]>:
> 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
