Gavin, others:
You are more then welcomed to "jump on in".
A few additional comments below.
-- 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 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 ;-) ).
Feel free to create an answer in the Developer's FAQ for this purpose.
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..
- 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.
- 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.
- Kurt
<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 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 ;-) ).
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).
Aye.
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:
http://directory.fedora.redhat.com/wiki/Users
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?
Thanks,
Gavin.
<quote who="Kurt D. Zeilenga">
<snip>
Feel free to create an answer in the Developer's FAQ for this purpose.
I've created a *very* basic page under this called:
"What documentation do we have, and what do we want?"
We can start with this, then I'll make it look a bit prettier later ;-)
Thanks.
P.S. Could you delete the 2 "New Item" pages I made by mistake ;-)
-
Gavin Henry -
Kurt D. Zeilenga