Mission: Having better end-user documentation for ApacheDS 2.0 (and beyond)
Problem Statement
The current documentation is
- incomplete
- outdated
- not really under maintenance
Reasons for this undesired state
- content creation and maintenance in different cwiki-Spaces, not linked to development version in svn
- too ambitious goals (e.g. different well organized guides)
- development not linked to documentation (basically 2 teams, from which 1 felt asleep)
Aims
- Set realistic goals which can be achieved by the documentation team until September 2008 (planned release of ApacheDS 2.0)
- unify documentation style with Studio subproject
Decisions
Basic User's Guide
We will convert the Basic User's Guide to DocBook comparable to the Studio documentation. It will be renamed to "ApacheDS Tutorial". And it will be the only documentation in the near future (2.0) which has the ambition to be a book. No Advanced User's Guide etc. anymore. They are currently too fragmented and incomplete. The Basic User's Guide on the other hand is nearly complete.
So the future of the ApacheDS Tutorial (ex Basic User's Guide) is
- content maintained in svn (sub project of ApacheDS)
- publish on our website as HTML and per download as PDF
All other Content
Instead of ambitious further guides we will simply have HowTos ("Recipes") on all topics imaginable. They are basically articles which are simpler to create and there is no need to create a book alike structure. A lot of content is already available which can be easily migrated to recipes. The main work here is to check whether they still work with the current trunk (and will still work with 2.0). Anyway, for some important topics there is still no documentation at all (like replication).
- Create standalone articles ("HowTos, Recipes")
- Maintain them in svn
- Publish them as HTML on our website (first)
 | A FAQ could be also usefull. It should contains informations about the most asked questions on the users mailing list, and pointers to the recipes. A good example would be : "How do I change the port" or "How do I inject a new schema" |
Tasks
- Create a sub project within the apacheds svn trunk for documentation
- Move content from the Basic User's Guide (1.5, 2.0 space) to svn, convert it to docbook
- Delete the ApacheDS2.0 space
Maven Project
The module for the documentation in svn could be found here: https://svn.apache.org/repos/asf/directory/sandbox/szoerner/apacheds-documentation
The repository folder contains a local maven repository with the docbook-xml and docbook-xsl libraries because the are not available in the public maven repository.
The tutorial folder contains a skeleton for the tutorial.
To build it change into the apachds-documentation directory and run "mvn install"
The generated userguides could be found under apacheds-documentation/target/userguides
The "tutorial" could be imported into Eclipse, run "mvn eclipse:eclipse" before.
DocBook documentation:
We use DocBook 4.5, the guide is available here: http://www.docbook.org/tdg/en/html/docbook.html
Content
Candidates for Recipes
The following table contains candidates for recipes. Basically, the idea is to finish all recipes of prio 1 and as may as possible with prio 2 until September.
| At some point, we may want to categorize the recipes. I can see something like :
(those are just suggestions) |
Configuring ADS
| Topics | content already available | priority (1=high) | volunteer | Remarks |
|---|---|---|---|---|
| How To enable SSL (LDPAS and StartTLS) |  |
1 | sz | outdated due to change in 1.5.2 |
| How to configure ApacheDS replication |  |
1 | ||
| How To configure SASL Authentication | |
2 |
Managing ADS and Developper information
| Topics | content already available | priority (1=high) | volunteer | Remarks |
|---|---|---|---|---|
| How to import another schema to ApacheDS | |
1 | sz | Use eduPerson as an example? |
| How To define and add your own elements to the schema | |
2 | sz | |
| How to use ApacheDS for unit tests | |
1 | stse | update to JUnit4 |
Using and configuring ADS with another product
| Topics | content already available | priority (1=high) | volunteer | Remarks |
|---|---|---|---|---|
| How To configure PAM Authentication with ApacheDS | |
3 | ||
| How To configure ApacheDS as a Tomcat realm | |
2 | sz | Currently in Basic User's Guide |
| How To configure Thunderbird to use ApacheDS | |
2 | ||
| How to run ApacheDS embedded in Geronimo | |
2 | sz | |
| How to embed ApacheDS as a Web Application | |
1 | sz | |
| How To configure JIRA to use ApacheDS | |
2 | ||
| How To configure Confluence to use ApacheDS | |
2 | ||
| How To configure ACEGI to use ApacheDS | |
2 | ||
| How To configure CAS to use ApacheDS | |
3 | ck | |
| How To configure Shibboleth to use ApacheDS | |
3 | ck |
Using the Kerberos Server
| Topics | content already available | priority (1=high) | volunteer | Remarks |
|---|---|---|---|---|
| How To use ApacheDS as a Kerberos Server | |
2 | ||
| Kerberos Client Configuration for OpenLDAP | |
3 | ||
| Kerberos Client Configuration for SSHD | |
3 | ||
| Kerberos Client Configuration for Wicket | |
3 | ck |
Extending ADS
| Topics | content already available | priority (1=high) | volunteer | Remarks |
|---|---|---|---|---|
| How To write Stored Procedures | |
2 | ||
| How To implement Triggers | |
2 | ||
| How To define and implement Extended Operations | |
2 | sz | |
| How To write your own Interceptor | |
2 |