From: Pedro Ferreira (pedro.ferreira_at_[hidden])
Date: 2003-10-17 03:43:17
> > When I look through the boost jam files for examples most of
> > what I see is undocumented. I know this is a work in progress.
> > Would it help for a neophyte like me to catalog undocumented
> > keywords?
> Frankly, I was never told how to write a good documentation. I'm putting
> issues that user raise into my notes with the hope to act on this
> one day. I think the best approach would be for you to continue posting
> messages about *any* omissions or obscurities in the documentation.
> In fact, I'd appreciate help about documentation structure, as well. From
> point of view, the tutorial is okay -- it's better to add an example for
> tutorial section, but it's okay anyway.
> But what should be written next? Complete reference of every feature. I'm
> afraid that it will be overwhelming. That's why the current doc have a
> "reference" section, indended to give only quick reference, and "detailed
> reference", which document every detail. Is this structure OK? Can you
> suggest all stuff which should go into "reference" section? I'd be
> for suggestions.
IMHO a complete, thorough reference would be a waste of time or, at least, a
misuse of time. I think that a tool like bjam would be well served with:
- For users:
- a tutorial that covers major use-cases. The one that exists is good,
it just needs a bit more material;
- a FAQ. I'm sure Volodya's notes would be a good start point;
- a thorough set of examples/test cases that can serve as templates.
- For developers:
- a reasonable amount/quality of comments in the code. I think it isn't
too bad as it is but could certainly be enhanced;
- a good set of architecture documents.
Another important point is the responsiveness of people in the list, which
IMO has been excellent, namely thanks to Volodya.
I'm willing to help in a documentation effort, so please count me in.
Just my 0.02,
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