Re: Comments on ORG ED

On 1 Oct 2012, at 16:18, Dave Reynolds wrote:
>> 1. Important: I'd prefer if the document was cleanly separated into two parts, where the second part is purely a reference of the classes and properties. Content like 7.1 or the intro to Section 10 should better be pulled up and presented before the class+property reference starts (before Section 6). Justification: I think very few people will read all the class+property reference front to back; but some may read all the early chapters front to back; so the bits of helpful discussion interspersed throughout the reference sections should be pulled out into the early chapters. Otherwise, they are too easy to miss.
> 
> Slightly tricky.
> 
> Many of the current discussion sections do not have enough detail to easily stand alone, but are intended to just clarify usage of the classes and properties which are the heart of the specification. I'm not sure how interpretable they on their own. Furthermore the grouping of discussion/detail into sections is intended to make it easy to skip the sections irrelevant to your task.
> 
> However, maybe I'm guilty of providing the style of document I would prefer myself. If I can allocate more time to this then I'll try a version as you suggest and see how it turns out.

Well, I concede that it may be a matter of taste, and it is ultimately an editorial issue. There are probably other issues with a higher cost-to-benefit ratio.

Best,
Richard

Received on Monday, 1 October 2012 17:42:07 UTC