Re: [boost] Change to documentation writing guidelines

Subject: Re: [boost] Change to documentation writing guidelines
From: Stewart, Robert (Robert.Stewart_at_[hidden])
Date: 2009-06-01 16:10:23

Daniel James wrote
On Monday, June 01, 2009 3:29 PM
> 2009/5/31 Daniel James <daniel_james_at_[hidden]>:
>
> Oh, I've got an objection myself. That part of the document concerns
> the C++ standard documentation guidelines, where this isn't
> appropriate. So instead I added an extra paragraph to the
> introduction:
>
> https://svn.boost.org/trac/boost/changeset/53551/trunk
> https://svn.boost.org/svn/boost/trunk/more/writingdoc/structure.html#introduction

The introduction is not a good place to document content requirements.  I suggest something like the following:

Introduction

   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.

   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

   ...

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:

   * Describe the enclosing namespace or use fully scoped
     identifiers.
   * Document required headers for each type or function.
   * Link to relevant tutorial information.
   * Link to related example code.
   * Include the library name.
   * Include navigation elements to the beginning of the
     documentation.

   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.

_____
Rob Stewart                           robert.stewart_at_[hidden]
Software Engineer, Core Software      using std::disclaimer;
Susquehanna International Group, LLP  http://www.sig.com

IMPORTANT: The information contained in this email and/or its attachments is confidential. If you are not the intended recipient, please notify the sender immediately by reply and immediately delete this message and all its attachments. Any review, use, reproduction, disclosure or dissemination of this message or any attachment by an unintended recipient is strictly prohibited. Neither this message nor any attachment is intended as or should be construed as an offer, solicitation or recommendation to buy or sell any security or other financial instrument. Neither the sender, his or her employer nor any of their respective affiliates makes any warranties as to the completeness or accuracy of any of the information contained herein or that this message or any of its attachments is free of viruses.