Subject: [Boost-commit] svn:boost r53611 - trunk/more/writingdoc
From: daniel_james_at_[hidden]
Date: 2009-06-03 18:48:11
Author: danieljames
Date: 2009-06-03 18:48:11 EDT (Wed, 03 Jun 2009)
New Revision: 53611
URL: http://svn.boost.org/trac/boost/changeset/53611
Log:
New introduction and web reference guidelines, by Robert Stewart.
Text files modified:
trunk/more/writingdoc/structure.html | 78 +++++++++++++++++++++++++--------------
1 files changed, 49 insertions(+), 29 deletions(-)
Modified: trunk/more/writingdoc/structure.html
==============================================================================
--- trunk/more/writingdoc/structure.html (original)
+++ trunk/more/writingdoc/structure.html 2009-06-03 18:48:11 EDT (Wed, 03 Jun 2009)
@@ -90,40 +90,36 @@
</dl>
</dd>
+ <dt>Web Reference Documentation</dt>
+
<dt>Footnotes</dt>
</dl>
<h2><a name="introduction" id="introduction">Introduction</a></h2>
- <p>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.</p>
-
- <p>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.</p>
-
- <p>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.</p>
-
- <p>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.</p>
-
- <p>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.</p>
+ <p>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.</p>
+
+ <p>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.</p>
<h2><a name="standards-conforming" id="standards-conforming">Standards
Conforming</a> Documentation</h2>
@@ -398,6 +394,30 @@
give users a lot of insight into why a library is designed the way it is.
More importantly, it can help prevent "fixing" something that wasn't really
broken as the library matures.</p>
+
+ <h2 id="web">Web Reference Documentation</h2>
+
+ <p>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:</p>
+
+ <ul>
+ <li>Describe the enclosing namespace or use fully scoped
+ identifiers.
+ <li>Document required headers for each type or function.
+ <li>Link to relevant tutorial information.
+ <li>Link to related example code.
+ <li>Include the library name.
+ <li>Include navigation elements to the beginning of the
+ documentation.
+ </ul>
+
+ <p>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.</p>
<h2><a name="footnotes" id="footnotes">Footnotes</a></h2>