Re: env vars, documentation (Was: [jamboost] environment variables)

From: Pedro Ferreira (pedro.ferreira_at_[hidden])
Date: 2003-10-17 03:43:17

Hi all,

> > 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
complains
> 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
my
> point of view, the tutorial is okay -- it's better to add an example for
each
> 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
greatefull
> 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,

Pedro