[Date Prev][Date Next] [Chronological] [Thread] [Top]

Re: Documentation Roadmap

<quote who="Kurt D. Zeilenga">
> Gavin, others:
> You are more then welcomed to "jump on in".

Cheers! ;-)

> A few additional comments below.

My replies below yours.

> -- Kurt
> At 02:28 AM 12/3/2006, Gavin Henry wrote:
>>Dear All,
>>After quite a few irc (#ldap) discussions with Howard and Quanah about
>> the
>>core docs, faq and man pages, I'd like to offer some thoughts on the way
>>forward and offer my time to help (somewhat limited, as is everyone's).
>>And, as I understand it from this years OpenLDAP conference, this is one
>>of the devel teams goals anyway.
>>My end goal for OpenLDAP, is to have documentation that equals or
>>surpasses the OpenLDAP software and setup a doc team to maintain it.
>>Q. So, who am I and why should you allow me to touch your docs?
>>A. We've commercially supported OpenLDAP for quite a while now (on your
>>list since 2003), with lots of deployments (every one of our clients), so
>>we hope we know the product. We also love documentation (weird, I know),
>>and most of our contributions to the community (docs and code) can be
>> seen
>>   http://www.suretecsystems.com/opensource/
>>varing from Amanda docs to sitting on the "Fedora Documentation Steering
>>Committee (FDSCo)"
>>Firstly, I'd like to get a page started on the FAQ system to track what
>>we've got, from all the man pages to guides etc. Then list whats
>>missing/needs improving. Also, a section for a wish list, which I see as
>>finishing/extenfing the Admin Guide, Starting a devel guide, and maybe a
>>User guide (using the tools with examples?) and a Roadmap to try and set
>>some dates (nothing like deadlines ;-) ).
> Feel free to create an answer in the Developer's FAQ for this
> purpose.

I'll start one and list all the man pages in 2.3.30 and guides, with
potentials for conversion/inclusion, this week.

>>Task Summary to start with (not in order or importance):
>>Man Pages:
>>* Check what's missing and unfinished
>>* Check for detail
>>* Identify what could be pulled into the Admin Guide for more examples
>>Admin Guide:
>>* Pull in info regarding all the different Overlays, uses and examples
>>* Pull in info regarding all the different backends, uses and examples
>>* Finish monitoring section, based on
>> "doc/guide/admin/monitoringslapd.sdf"
>>* More discussion of Replication Scenarios, with complete examples
>>* More in depth Quick start, maybe from install to replicated setup etc.
>>* Extend Schema Section
>>* Tuning section
>>* Identify core good parts from FAQ, and bring into guide
>>* Many more....
>>Devel Guide:
> But I do think it would be good to produce a developer's guide, but
> in doc/guide/devel..

Of course, that's what I meant. But shouldn't we have it on the main site
too, under http://www.openldap.org/doc/ ???

>>* Turn doc/devel/* into a guide
> Most everything in directory should stay as it is (maybe incorporated
> in the guide as appendices or something.   Except utfconv.txt,
> it, as the todo file says, should be incorporated into manual pages.

Agreed. As part of the PDF/HTML offering of the guide, I think, listed
beside it, should be a tar/zip of all the guide with the code
examples/coding practices etc.

Or, they will probably be checking out the source anyway, so above comment
wouldn't apply.

>>* use servers/slapd/overlays/slapover.txt for info about all hooks/flow
>>control of slapd etc.
>>* Many more....
>>User Guide:
>>* Identify if one is needed
> s/User/End User/ (e.g., not administrative user of OpenLDAP Software).


> and, more importantly, whether we want to produce and maintain one.

This has been bugging me. I think we leave all the other projects to
provide integration docs. How about a Deployment guide instead, or would
that fall under the Admin guide? The Deployment Guide could have real
world cases etc. in it and the tuning/monitoring section.

The idea came from peeking at the fds stuff (The main docs are still the
ones Red Hat bought from Netscape:


Lastly, what are your thoughts on a Wiki based system for rough TOC drafts
etc. for new authors? Or should it be tracked on Devel FAQ and ITS for
draft submissions?



Kind Regards,

Gavin Henry.
Managing Director.

T +44 (0) 1224 279484
M +44 (0) 7930 323266
F +44 (0) 1224 824887
E ghenry@suretecsystems.com

Open Source. Open Solutions(tm).