Extra guidelines for web documentation, and some editorial changes. Fixes #2214

Merged revisions 53551,53611-53613,53637 via svnmerge from 
https://svn.boost.org/svn/boost/trunk

........
  r53551 | danieljames | 2009-06-01 20:18:00 +0100 (Mon, 01 Jun 2009) | 1 line
  
  Extra guidelines for writing documentation for the web.
........
  r53611 | danieljames | 2009-06-03 23:48:11 +0100 (Wed, 03 Jun 2009) | 1 line
  
  New introduction and web reference guidelines, by Robert Stewart.
........
  r53612 | danieljames | 2009-06-03 23:48:22 +0100 (Wed, 03 Jun 2009) | 2 lines
  
  Use the second paragraph of Robert's introduction as an introduction to the standard guidelines section.
  Reintroduce the reference to the standard and link to the 'more information' section.
........
  r53613 | danieljames | 2009-06-03 23:48:35 +0100 (Wed, 03 Jun 2009) | 1 line
  
  Link footnotes back to their location in the document.
........
  r53637 | danieljames | 2009-06-04 17:43:30 +0100 (Thu, 04 Jun 2009) | 1 line
  
  Writing docs tweaks from Robert Stewart.
........


[SVN r53683]

Author: danieljames

more/writingdoc/structure.html

@@ -90,40 +90,44 @@ <h2 align="center">Documentation Structure</h2>
       </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>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>
 
   <h2><a name="standards-conforming" id="standards-conforming">Standards
   Conforming</a> Documentation</h2>
 
+  <p>The documentation structure required for the C++ 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.
+  The following description is based upon &sect;17.3 of the
+  Standard.  (Note that while final Standard proposals must
+  include full standardese wording, which the committee will
+  not do for you, that level of detail is not expected of Boost
+  library documentation.)</p>
+
   <h3><a name="elements" id="elements">Document elements</a></h3>
 
   <p>Each document contains the following elements, as applicable<a class=
-  "footnote" href="#footnote1">(1)</a>:</p>
+  "footnote" href="#footnote1" id="footnote1-location">(1)</a>:</p>
 
   <ul>
     <li><a href="#summary">Summary</a></li>
@@ -197,7 +201,7 @@ <h4><a name="requirements" id="requirements">Requirements</a></h4>
   <p>In some cases the semantic requirements are presented as C++ code. Such
   code is intended as a specification of equivalance of a construct to
   another construct, not necessarily as the way the construct must be
-  implemented.<a class="footnote" href="#footnote2">(2)</a></p>
+  implemented.<a class="footnote" href="#footnote2" id="footnote2-location">(2)</a></p>
 
   <h4><a name="detailed-specs" id="detailed-specs">Detailed
   specification</a></h4>
@@ -218,7 +222,7 @@ <h4><a name="detailed-specs" id="detailed-specs">Detailed
   </ul>
 
   <p>Descriptions of class member functions follow the order (as
-  appropriate)<a class="footnote" href="#footnote3">(3)</a>:</p>
+  appropriate)<a class="footnote" href="#footnote3" id="footnote3-location">(3)</a>:</p>
 
   <ul>
     <li>Constructor(s) and destructor</li>
@@ -236,7 +240,7 @@ <h4><a name="detailed-specs" id="detailed-specs">Detailed
 
   <p>Descriptions of function semantics contain the following <a name=
   "function-elements" id="function-elements">elements</a> (as
-  appropriate)<a class="footnote" href="#footnote4">(4):</a></p>
+  appropriate)<a class="footnote" href="#footnote4" id="footnote4-location">(4):</a></p>
 
   <dl class="function-semantics">
     <dt><b><a href="#requires">Requires:</a></b> the preconditions for
@@ -390,24 +394,48 @@ <h4><a name="rationale" id="rationale">Rationale</a></h4>
   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>
 
   <dl>
-    <dt><a class="footnote" name="footnote1" id="footnote1">(1)</a> To save
+    <dt><a class="footnote" id="footnote1" href="#footnote1-location">(1)</a> To save
     space, items that do not apply to a clause are omitted. For example, if a
     clause does not specify any requirements, there will be no "Requirements"
     subclause.</dt>
 
-    <dt><a class="footnote" name="footnote2" id="footnote2">(2)</a> Although
+    <dt><a class="footnote" id="footnote2" href="#footnote2-location">(2)</a> Although
     in some cases the code is unambiguously the optimum implementation.</dt>
 
-    <dt><a class="footnote" name="footnote3" id="footnote3">(3)</a> To save
+    <dt><a class="footnote" id="footnote3" href="#footnote3-location">(3)</a> To save
     space, items that do not apply to a class are omitted. For example, if a
     class does not specify any comparison functions, there will be no
     "Comparison functions" subclause.</dt>
 
-    <dt><a class="footnote" name="footnote4" id="footnote4">(4)</a> To save
+    <dt><a class="footnote" id="footnote4" href="#footnote4-location">(4)</a> To save
     space, items that do not apply to a function are omitted. For example, if
     a function does not specify any precondition, there will be no "Requires"
     paragraph.</dt>