New introduction and web reference guidelines, by Robert Stewart.

[SVN r53611]

more/writingdoc/structure.html

@@ -90,40 +90,36 @@
       </dl>
     </dd>
 
+    <dt><a href="#web">Web Reference Documentation</a></dt>
+
     <dt><a href="#footnotes">Footnotes</a></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 @@ void resize(size_type n, charT c);
   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>