On Friday 08 December 2006 07:14, Ericka Abraham wrote:
> David Abrahams wrote:
>
> > If I consider all the places in our documentation that could benefit
> > from the sort of professional attention I've been describing, the one
> > that causes the most problems for people day-to-day is in the
> > Boost.Build documentation.
>
> I would be happy to work on the Boost.Build documentation. I am a
> little unclear as to which specific pages need the most help, however.
> This page:
> http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?Boost.Build/Documentation_Issues
>
> tells me that the manual, which I assume means this:
> http://boost.org/boost-build2/doc/html/index.html manual, needs to be
> broken up into three separate documents. I believe I could handle the
> first two challenges, which are the manuals for users and extenders, but
> I am not certain that my scripting knowledge extends far enough to
> prepare a document for expert users. Though I am certainly willing to
> try. Is this correct? I've also found this page:
> http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?Boost.Build_V2/Documentation_Todo
>
> which details other tasks needing completion, but again I am unsure of
> what needs to be done, as some of these pages haven't been updated in
> quite some time.
Hi Ericka,
I think both of Wiki pages you've referred to are a little bit out of date. In
particular,
the documentation for extenders is now a separate section, and I don't think
documentation for "hackers" is high priority.
>From my point of view, Boost.Build docs have the following problems:
- Reference. Many users have commented that the reference is
far incomplete. Many existing rules/types and so on are not documented.
- Many users said that "it's hard to find things". I've tried to fix
that
by explicitly separating "Tasks" section, and improved reference should
help too, maybe indexes will help. But generally, I'm not expert in
docs,
I just don't know what will work out here.
- Proofreading. Some time ago, Dave has left a lot of editorial
comments though the docs, I only was able to address half of them,
or even less.
- Some better overviews. For example, the "Overview" section should
probably start with describing most important concepts and how
they mesh together.
- New functionality/tasks docs. Sometimes user ask questions that
are not in docs, and sometimes new code is added. It would be great
to have all this end up in docs.
Some of this obviously requires being able to play with Boost.Build first-hand,
to verify
that the text agrees with code behaviour. So if you'll decide to take this
project, you'd need to
get acquainted with the basic concepts and try some small examples. But I don't
think any in-depth
knowledge is needed.
It surely would be great to have you helping with Boost.Build documentation!
- Volodya
-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys - and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
Boost-docs mailing list
[email protected]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
