From 8b3b668ec4176d319a792627c1e770bb71750246 Mon Sep 17 00:00:00 2001 From: Daniel James Date: Wed, 3 Jun 2009 22:48:11 +0000 Subject: [PATCH] New introduction and web reference guidelines, by Robert Stewart. [SVN r53611] --- writingdoc/structure.html | 76 ++++++++++++++++++++++++--------------- 1 file changed, 48 insertions(+), 28 deletions(-) diff --git a/writingdoc/structure.html b/writingdoc/structure.html index b631785..af38aa8 100644 --- a/writingdoc/structure.html +++ b/writingdoc/structure.html @@ -90,40 +90,36 @@ +
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.

+

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.

Standards Conforming Documentation

@@ -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.

+ +

Web Reference 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.

Footnotes