Re: [jamboost] Re: Docs structure

From: Vladimir Prus (ghost_at_[hidden])
Date: 2004-12-14 11:20:05

On Tuesday 14 December 2004 18:54, David Abrahams wrote:
> 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? 

No, it's true.

> They do seem to overlap significantly, and 
> some of the important information can only be found in the tutorial.

That's bad, I think.

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

> 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'm trying, too.

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

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

Probably, but I still find it important to outline few important features in 
tutorial, where new users can easily find it. If, say, usage-requirements are 
documented deep in user manual, few users will find them.

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

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.

- Volodya