Boost itself does not require any specific documentation structure. The - C++ Standard, however, has very explicit requirements for the description - of library components (Section 17.3). So for Boost libraries likely to be - proposed for inclusion in the standard, it is highly desirable to structure - documentation in a way that meets the requirements of the the standard. - Doing so eliminates the need to rewrite the documentation for - standardization.
+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.
-Library developers should remember that for a library to be accepted as - part of the C++ Standard Library, the proposal must include full wording. - The committee will not do that work for you.
- -Beyond that, the documentation structure required for the standard is an - effective way to communicate the technical specifications for a library. - Although terse, it is already familiar to many Boost users, and is far more - precise than most ad hoc documentation structures.
- -The following description is for the structure of documentation required - by the standard. Boost libraries should also provided additional - documentation, such as introductory, tutorial, example, and rationale - material.
- -Since the documentation is also intended to act as a web reference, it's a - good idea to add some extra information to individual pages, especially - detailed reference pages. Full C++ identifiers and required headers are - especially useful and often overlooked. Remember that individual pages might - be accessed directly from a search engine or link, so readers won't have seen - information from previous pages. In reference pages, it can be helpful to link - to relevant tutorial information.
+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.
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:
+ +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.