From: Vladimir Prus (ghost_at_[hidden])
Date: 2005-01-26 04:40:30
> >> I am now confident that I know how the docs should be structured. The
> >> tutorial is pretty good (or will be as soon as soon as you go through
> >> our edits), but there's a terrible amount of redundancy with the next
> >> chapter. The tutorial should become the beginning of that chapter, and
> >> the redundancy should be removed.
> > Do you mean that the tutorial and current "User manual" should form one
> > section? Or simply that they should form a logical sequence with no
> > duplication? Either variant is OK, I'm just trying to clarify.
> Either variant is OK with me, too, but I had the former in mind.
Ok, let's try this.
> > Maybe hardcode-dll-paths deserves a tip
> 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.
> > 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
> > 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? Can we assume he'll just right to "builtin rules"?
Of consider "Writing Jamfiles" section. If a user wants to know the syntax for
declaring main target, will he guess that he should read the "Writing
Boost-Build list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk