Daniel James wrote On Monday, June 01, 2009 3:29 PM
2009/5/31 Daniel James <daniel_james@fmail.co.uk>:
Oh, I've got an objection myself. That part of the document concerns the C++ standard documentation guidelines, where this isn't appropriate. So instead I added an extra paragraph to the introduction:
https://svn.boost.org/trac/boost/changeset/53551/trunk https://svn.boost.org/svn/boost/trunk/more/writingdoc/structure.html#introdu...
The introduction is not a good place to document content requirements. I suggest something like the following: Introduction Boost does not require any specific documentation structure. However, there are some important considerations that influence content and structure. For example, many Boost libraries wind up being proposed for inclusion in the C++ Standard, so writing them initially with text suitable for inclusion in the Standard may be helpful. Also, Boost library documentation is often accessed via the World Wide Web, including via search engines, so context is often important for every page. Finally, Boost libraries should provide additional documentation, such as introductory, tutorial, example, and rationale content. With those things in mind, we suggest the following guidelines for Boost library documentation. The documentation structure required for the standard is an effective way to describe the technical specifications for a library. Although terse, that format is familiar to many Boost users and is far more precise than most ad hoc formats. Below is a description of the Standard documentation structure. Note that Standard proposals must include full standardese wording, which the committee will not do for you, to be accepted. That level of detail is not expected of Boost library documentation. Standards Conforming Documentation ... Web Reference Documentation Boost library documentation is often accessed via the World Web. Using search engines, a page deep in the reference content could be viewed without any further context. Therefore, it is helpful to add extra context, such as the following, to each page: * Describe the enclosing namespace or use fully scoped identifiers. * Document required headers for each type or function. * Link to relevant tutorial information. * Link to related example code. * Include the library name. * Include navigation elements to the beginning of the documentation. It is also useful to consider the effectiveness of a description in search engines. Terse or cryptic descriptions are less likely to help the curious find a relevant function or type. _____ Rob Stewart robert.stewart@sig.com Software Engineer, Core Software using std::disclaimer; Susquehanna International Group, LLP http://www.sig.com IMPORTANT: The information contained in this email and/or its attachments is confidential. If you are not the intended recipient, please notify the sender immediately by reply and immediately delete this message and all its attachments. Any review, use, reproduction, disclosure or dissemination of this message or any attachment by an unintended recipient is strictly prohibited. Neither this message nor any attachment is intended as or should be construed as an offer, solicitation or recommendation to buy or sell any security or other financial instrument. Neither the sender, his or her employer nor any of their respective affiliates makes any warranties as to the completeness or accuracy of any of the information contained herein or that this message or any of its attachments is free of viruses.