Documentation Roadmap

["Gavin Henry" <ghenry@suretecsystems.com>]

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
at:

   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 ;-) ).

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:

* Turn doc/devel/* into a guide
* 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


I checked out the *sdfs a few weeks ago, and although most of my work is
done in DocBook XML, SDF looks easy, converts well to PDF, which d-xml
doesn't (more info about Fedora Tool-chain if needed), so I'm not
proposing a conversation. Let's stick with defining and writing content.

When we get a good team together and have more docs, maybe OpenLDAP will
stop being bashed about quality of docs and people will actually get on to
contributing instead of whining.

You never know, people might read them before posting to the lists and
save us all time in the long run!

Thanks for your time and look forward to your responses,

Gavin.

-- 
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).

http://www.suretecsystems.com/