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-04 08:15:40

Daniel James wrote
On Wednesday, June 03, 2009 7:06 PM
> 2009/6/1 Stewart, Robert <Robert.Stewart_at_[hidden]>:
> >
> > The introduction is not a good place to document content
> > requirements.  I suggest something like the following:
[snip]
>
> I thought that your second paragraph seemed to mainly apply to the
> first section of the document, so I moved it into that section, and
> tried to give a slightly better idea of how it relates to the next
> section. I also put back in the section of the standard that it's
> taken from as I think that's important.
>
> https://svn.boost.org/trac/boost/changeset/53612
>
> Does that seem sensible?

At first, I didn't think it was appropriate to move that paragraph because I intended it to be part of the introduction to frame what was to come.  However, seeing the result, I agree with you, especially as it is similar to the first paragraph of the Web Reference Documentation section.

I have a few wording changes to suggest to that moved paragraph:

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

Note that I've eliminated your #more anchor because I think much more than the targeted section fits that description and that we shouldn't encourage the reader to skip the rest of the material.

I wonder if that section number will continue to apply in the C++0x Standard, when finished.  If not, I guess we'll have to clarify it with the version of the Standard.

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