Re: Docs structure

From: David Abrahams (dave_at_[hidden])
Date: 2004-12-14 12:05:32

Vladimir Prus wrote:
> On Tuesday 14 December 2004 18:54, David Abrahams wrote:
>> Vladimir Prus wrote:
>> 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've not much experience with the former. Regarding the latter -- I don't 
> think I've used tutorial. Requirements for derived type (for iterator_facade) 
> were enough.

Well, I can tell you that demand for the sort of walkthrough we now
provide was exceedingly high.

>> > 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.
> 
> I'm not sure about this. I always though that V2 tutorial just can contain 
> enough information to be used on a daily basis.

For those who are only doing simple things, as many people are, it could.

>> > 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.
> 
> Probably, but I still find it important to outline few important features in 
> tutorial, where new users can easily find it. 

I agree.

> If, say, usage-requirements are 
> documented deep in user manual, few users will find them.

If you keep the tutorial walkthrough small enough and the user manual
accessible enough, more people will move on to the manual sooner. I
think with some cleanup it could be very easy to read.

>> >> 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.
> 
> I can compare this to Boost libraries which have Boostbook + doxygen docs. 
> Boostbook parts cover higher level things. doxygen parts have docs for each 
> method of every class. If you try to merge it together, the result will be 
> unusable. We need to somehow separate commonly needed information from rarely 
> needed.

It's my opinion that if you do that there will be many things for which
the information in the reference and the user manual are exact
duplicates of one another. But why don't I finish going through
everything, and then we'll see?

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