[Freeipa-devel] Planning FreeIPA Upstream Doc changes

[JR Aquino]

On Aug 8, 2013, at 12:19 AM, "Martin Kosek" <mkosek at redhat.com> 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

^ +1

And I agree that a preliminary should be hosted on the FreeIPA.org project portal rather than the fedora documentation site. It feels more natural that way.

Ideally, it should be trivial to check out or grab the relevant rpm for a given version as we move forward into new releases, that way an admin can view the doc that refers specifically to their running release rather than be confused about up-to-date features that may not exist on theirs.

> 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

^+1

I've always found it a little awkward to hunt docs down at the fedora documentation portal.
> 
> 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
> 

Thanks carrying the torch!

> -- 
> Martin Kosek <mkosek at redhat.com>
> Supervisor, Software Engineering - Identity Management Team
> Red Hat Inc.
> 
> _______________________________________________
> Freeipa-devel mailing list
> Freeipa-devel at redhat.com
> https://www.redhat.com/mailman/listinfo/freeipa-devel