[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
>>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.
--
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/