Subject: Re: [boost] Change to documentation writing guidelines
From: Stewart, Robert (Robert.Stewart_at_[hidden])
Date: 2009-06-01 16:10:23
Daniel James wrote
On Monday, June 01, 2009 3:29 PM
> 2009/5/31 Daniel James <daniel_james_at_[hidden]>:
> 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
The introduction is not a good place to document content requirements. I suggest something like the following:
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
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
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
* 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
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
Rob Stewart robert.stewart_at_[hidden]
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.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk