Re: [boost] Improving Boost Docs

Subject: Re: [boost] Improving Boost Docs
From: Vinnie Falco (vinnie.falco_at_[hidden])
Date: 2017-08-14 16:12:25

On Mon, Aug 14, 2017 at 8:29 AM, Andrzej Krzemienski via Boost
<boost_at_[hidden]> wrote:
> I do not even know if there is a consensus about what "look and feel" is.

The "look and feel" is a subjective quality where the reader
recognizes a rendered subset of documentation as belonging to a larger
work based on visual elements. These elements include:

* Boost banner at the top of the page

* Sans-serif on white background

* 4-icon nav bar in top right and top left ( BACK, UP, HOME, FWD )

* Source code blocks are indented, in a fixed width font, with a thin
gray rectangle outlining the block

* Paragraphs flow to the width of the window in which they are rendered

* No frames or iframes (sorry Robert!)

* Table of contents, if present, is at the top of the page, surrounded
by a thin gray rectangle

* Standard dingbats (bullets for unordered lists)

* Standard admonition icons and formatting (thin gray rectangle), see:
<http://www.boost.org/doc/libs/1_64_0/doc/html/quickbook/syntax/block.html#quickbook.syntax.block.admonitions>

> Is it only the fonts and colors, or is it also the same structure of
> documentaion in all libraries: short intro first, then tutorial, then
> reference section.

Writing, like coding, is a creative endeavor and while there are
useful guidelines for how documentation should be structured, every
library is unique and each library author has to make the best choices
for how the library will be presented in the documentation. I don't
think it would be helpful to prescribe a meta template for the content
of the work. I DO think it is helpful to provide tips and tricks to
help writers get ideas for how to present their work. And also to
serve as inspiration when that inevitable writer's block strikes.

Thanks