Re: [jamboost] Re: The right documentation structure.

From: David Abrahams (dave_at_[hidden])
Date: 2005-01-26 13:38:01

Vladimir Prus <ghost_at_[hidden]> writes:

>> I'm guessing a brief mention in a table (if anything) is more
>> appropriate. The user guide shouldn't go into an explanation of why you
>> might want to use the feature. Someone who knows about the issue will
>> know why. Someone who doesn't should use the built-in testing rules
>> first, and only resort to hardcode-dll-paths as a last resort.
>
> My edits in tutorial.xml drop hardcode-dll-path completely. After all, it's a 
> nice feature of Unix that just works, so beginners should not care.

Good.

>> > Say, where the overview of build process:
>> >
>> > 
>> > http://boost.org/boost-build2/doc/html/bbv2/advanced/build_process.html
>> >
>> > belong?
>>
>> It's fine for that to be in the User Guide, but it has to be edited. It
>> has too much low-level information in it and makes assumptions about the
>> user's understanding of BB internals. I haven't checked in my notes
>> there yet.
>
> I went though your notes there and I think understood most of them. I'll now 
> edit advanced.xml.

Okay. I'm proceeding with a page per day of edits to extending.xml.

>> > We already have user/extender docs separation -- which is good, but I
>> > think we should strive to avoid the user manual becoming a set of 30
>> > sections without further structure.
>>
>> It would be a good time to look at the topics you're covering there and
>> try to organize them into a hierachical structure, while simultaneously
>> looking for what's missing that you want to cover (otherwise you might
>> find some isolated bit that will really be accompanied by lots more but
>> that looks too small to stand in a section by itself).
>
> There's still a problem for me. Say, we have section "Builtin rules" which 
> describes "alias", "unit-test" , installing and so on. If we make each rule 
> into a separate section, documentation looses any structure. If we retain the 
> current structure, then how a user which wants to install things can find the 
> relevant section? 

?? That's why I was suggesting you make an outline of everything that
should be covered there and try to organize it into hierarchical
structure. Somehow your reply here sounds as though you didn't
understand me.

I think it's reasonable to assume that there will be a fair amount to
cover about installing (more than just one rule), and likewise about
testing rules. So I think these should be organized into "builtin
tools" or "builtin modules" based on the sort of work they are
good for:

...
Builtin Modules
test
install
python
...
...

Probably "alias" would fall into a section about general utility
rules... although, it seems to serve so many purposes that a separate
section on alias and how to use it might be a good idea.

> Can we assume he'll just right to "builtin rules"?

He'll just ______ (jump?) right to "builtin rules?"

> Of consider "Writing Jamfiles" section. 
["Of" doesn't belong there]

> If a user wants to know the syntax for declaring main target

You mean the "common syntax?"

> will he guess that he should read the "Writing Jamfiles" section?

Well, in some sense you can't do anything without understanding how to
write Jamfiles, so it wouldn't be so bad if you had to read that. But
it also seems as though the common syntax for main targets is a
fundamental organizing principle of Boost.Build. So there should be a
"fundamentals" section that describes the main concepts (the domain
abstractions) of Boost.Build and covers basics like the common syntax.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com