[Freeipa-devel] Planning FreeIPA Upstream Doc changes

[Martin Kosek]

Hello all,

This is a follow up for upstream doc maintenance questions I had on
freeipa-users in June:
http://www.redhat.com/archives/freeipa-users/2013-June/msg00202.html

As Content Writer taking care of the User Guide (on docs.fedoraproject.org) no
longer has resources to maintain it and the guide become partially outdated.
FreeIPA development team and community will need to take over as it was agreed
this is of a great benefit to the project.

I would like to propose a plan to revive the guide:

1) Move FreeIPA Guide out of current Deon's git tree (hosted on
https://fedorahosted.org/freeipa-guide/) to git owned by FreeIPA. There are 2
options:
A) Host and package it in current FreeIPA git along with a code. Handling the
doc patches would be much simpler, however it would mean, that the docs for
next version would need to be prepared at the time when code is ready for
release which could either postpone the release and release with incomplete doc
(this introduces question how should the git be tagged/branched).
B) Add a new git tree to FreeIPA fedorahosted account (freeipa/docs.git) and
release the docs asynchronously to the code (there could be of course a
preliminary version on FreeIPA.org site). I was already thinking about options
to seamlessly integrate an RPM with docs to FreeIPA Web UI which could then
provide relevant help links from the UI dialogs to the right spots of
documentation.
- so far, it seems that option B) will get us more flexibility and would avoid
people contributing to the code only downloading also the doc.
WHEN: this step would be right after the plan is acknowledged

2) Update the guide to match FreeIPA 3.3
- currently, the guide is approximately on FreeIPA 3.1 level
- I filed Trac tickets for gaps I identified in the guide:
https://fedorahosted.org/freeipa/milestone/Revive%20FreeIPA%20guide
- I would keep the guide in Docbook format unless there are strong reasons to
use other format and avoid loosing information. It is very easy to generate all
sorts of formats (html, pdf, epub) out of Docbook with publican utility which
is packaged in Fedora -> easy build in koji
- ideally, editorial would be done by a potential contractor we identified
WHEN: most should be done in August, some can be done in September

3) Host the result on FreeIPA.org
- we used to release to Fedora documentation portal, but I am thinking it would
be more natural to host a project site on project portal instead of Fedora
Documentation which rather holds general Fedora infrastructure books. It may be
also more intuitive for users to find it on FreeIPA.org than on Fedora docs.
- we can take advantage of publican and build a doc site like
"docs.freeipa.org" which would held publican-managed doc site with our guides.
I tried to play with publican and this is a first PoC result:
http://mkosek.fedorapeople.org/publican_site/
- I would prefer if our generated user guides (including current Extending
guide hosted on abbra.fedorapeople.org site) use Docbook + be integrated in the
site + wiki to have them all under the same roof with consistent look
WHEN: Before FreeIPA 3.4 is released

4) Start maintaining and releasing User guide with FreeIPA releases
- revive "Affects doc" Trac ticket flag and make sure that Doc is updated along
with RFEs and bugfixes
- the process of tracking and doing the doc updates and changes is essential in
order to keep the doc updated and useful for our users
- ideally, editorial would be done by a contractor
WHEN: Before 3.4 is release

Any ideas or comments very welcome.

Thanks,
Martin

-- 
Martin Kosek <mkosek at redhat.com>
Supervisor, Software Engineering - Identity Management Team
Red Hat Inc.