From 5dc0faa12d705e3b9bb53efd9ebe3f826a8a3b2c Mon Sep 17 00:00:00 2001 From: Daniel James Date: Sat, 6 Jun 2009 13:17:08 +0000 Subject: [PATCH] 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] --- more/writingdoc/structure.html | 86 ++++++++++++++++++++++------------ 1 file changed, 57 insertions(+), 29 deletions(-) diff --git a/more/writingdoc/structure.html b/more/writingdoc/structure.html index 900f2a61a8fe..c38b554c7a06 100644 --- a/more/writingdoc/structure.html +++ b/more/writingdoc/structure.html @@ -90,40 +90,44 @@

Documentation Structure

+
Web Reference Documentation
+
Footnotes

Introduction

-

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.

- -

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.

+

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.

Standards Conforming Documentation

+

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 §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.)

+

Document elements

Each document contains the following elements, as applicable(1):

+ "footnote" href="#footnote1" id="footnote1-location">(1):

Descriptions of class member functions follow the order (as - appropriate)(3):

+ appropriate)(3):