[Freeipa-devel] Planning FreeIPA Upstream Doc changes

[Martin Kosek]

On 08/08/2013 09:19 AM, Martin Kosek wrote:
> 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
> 

Note that FreeIPA User Guide was successfully moved to new FreeIPA git repo.
All our contribution should be based on it.

See http://www.freeipa.org/page/Contribute/Documentation for more information
about handling the documentation and submitting changes.

Martin