2009/5/31 Sebastian Redl <sebastian.redl@getdesigned.at>:

Daniel James wrote:

...

I'd like to change the guideline for writing reference documentation to include header and namespace information in the detailed documentation. If you arrive at a page by a link or from a search engine, it isn't always easy to work this out. I'll add them to the list here:

http://beta.boost.local/doc/libs/release/more/writingdoc/structure.html#deta...

Boostbook documentation already includes this. Any objections?

Your link is invalid.

Sorry, that was my local server. http://www.boost.org/doc/libs/release/more/writingdoc/structure.html#detaile... Daniel

Daniel James wrote On Monday, June 01, 2009 3:29 PM

2009/5/31 Daniel James <daniel_james@fmail.co.uk>:

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#introdu...

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

2009/6/1 Stewart, Robert <Robert.Stewart@sig.com>:

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

[snip] Yeah, you're probably right. I was trying to change as little as possible but what your version works well. I've added it here: https://svn.boost.org/trac/boost/changeset/53611 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? Any other suggestions are very welcome. The lasted version in trunk can be seen at: http://svn.boost.org/svn/boost/trunk/more/writingdoc/structure.html Daniel

2009/6/4 Stewart, Robert <Robert.Stewart@sig.com>:

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

OK, I'll check in your changes later.

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.

I looked at the current draft last night and the section number is a little different (something like 17.5), so I'll do that. Daniel

Edward Diener wrote On Monday, June 01, 2009 9:37 AM

...

I'd like to change the guideline for writing reference documentation to include header and namespace information in the detailed documentation.

I think it will make it easier and quicker to use library functionality when header and namespace is explicitly stated for the classes and functions in a library in the reference docs. Hopefully library authors will follow up with this in their own documentation.

+1 _____ Rob Stewart robert.stewart@sig.com 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.

2009/6/1 Edward Diener <eldiener@tropicsoft.com>:

Thanks for pushing this through. I know I suggested this in a Trac ticket and, as an end user of Boost libraries, I think it will make it easier and quicker to use library functionality when header and namespace is explicitly stated for the classes and functions in a library in the reference docs. Hopefully library authors will follow up with this in their own documentation.

Yeah, this is so that I can close that ticket. I wouldn't expect anything new from existing documentation, although library authors may be willing to accept patches. Although, if you want anything more from the boostbook based documentation I might be able to do something. Daniel

2009/6/3 David Abrahams <dave@boostpro.com>:

I'm afraid to say this, because I know some of my older libraries don't conform to the guidelines at all, but...

I think we've developed enough guidelines that it would be a good idea for _someone_ (ahem!) to go through the docs and create tickets for all the places where our existing documentation doesn't conform.  That would at least give lib maintainers an opportunity to face the question of whether they're going to make the fix. :-)

Maybe, but the guidelines repeatedly make the point that they're not compulsory so I've always seen them as optional. Daniel