FYI. I originally posted the planing to the freeipa-devel list as it affects mostly developers, but it may be interesting for some of our users too.
Martin -------- Original Message -------- Subject: [Freeipa-devel] Planning FreeIPA Upstream Doc changes Date: Thu, 08 Aug 2013 09:19:21 +0200 From: Martin Kosek <mko...@redhat.com> To: freeipa-de...@redhat.com 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 <mko...@redhat.com> Supervisor, Software Engineering - Identity Management Team Red Hat Inc. _______________________________________________ Freeipa-devel mailing list freeipa-de...@redhat.com https://www.redhat.com/mailman/listinfo/freeipa-devel _______________________________________________ Freeipa-users mailing list Freeipafirstname.lastname@example.org https://www.redhat.com/mailman/listinfo/freeipa-users