Re: Docs structure

From: David Abrahams (dave_at_[hidden])
Date: 2004-12-14 10:54:47

Vladimir Prus wrote:
> On Tuesday 14 December 2004 16:46, David Abrahams wrote:
> 
>> > I envision the structure to be
>> >
>> > 1. Tutorial (just nice examples for new users)
>> > 2. User documentation. It should document everything, but in a verbose
>> > way, and without all the details.
>>
>> The tutorial and the user documentation, as they stand today, cover much
>> of the same ground. 

Do you disagree with this? They do seem to overlap significantly, and
some of the important information can only be found in the tutorial.

>> I think the tutorial material should be merged into
>> the user documentation, and we should start the user documentation with
>> a simple tutorial walkthrough of a "hello world" and proceed a slightly
>> more complex example using libraries.
> 
> I don't agree. Tutorial is more like ad. Users read it to get overall 
> impression of features. 

I find it hard to believe that you believe that is true in general. Can
you imagine if the Boost.Python library or the iterators library
tutorials were just like an ad? People would be completely lost.

I suggest you may not be the best judge of what will work for other
people in terms of documentation. I am the same way, when it comes to
my own work, so I try to listen hard to the people that have to use my docs.

> I don't expect it to be very useful for regular work.

For many people, a tutorial is the best way for them to begin getting
their hands dirty and serves as their primary source of insight about
any tool or library for a _long_ time after. Eventually they graduate
to a detailed reference.

>> > 3. Reference (has all the details for user visible features, but too
>> > dense for general users.
>>
>> I am guessing that we don't have the time or energy to maintain this in
>> addition to the User Documentation. The structure as you describe it
>> here means that every time something changes you might have to edit 3 or
>> 4 different sections of the docs. 
> 
> Why 3 or 4. Tutorial should require no change at all, unless we introduce 
> something extra cool. 

Or if we just change how something that's covered in the tutorial works.

When you see the comments in my edits you will understand. It's in part
because the tutorial is reaching into territory it probably shouldn't go
into.

> Most user visible feature require tweaking user docs 
> and maybe reference.
> 
>> We should limit that to 1 or 2. So I 
>> propose that we try hard to get the neccessary details into the user
>> documentation in a way that's readable and coherent. 
> 
> Is it possible without getting unreadable? Say, can be add syntax of target id 
> into user documentation? 

Yes, and we should. It's really fundamental to using the system.

>> When certain 
>> subjects demand more attention, we can add an appendix that we reference
>> from the main part of the manual.
> 
> That's almost how user manual/reference work. User manual links to reference 
> when details are too numerous to include in user manual.

But a reference is expected to cover *everything*, rather than just
particular details. I suggest that what you've got here will require
too much maintenance to be practical.

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com