[Freeipa-users] What should we do with upstream guide?

[Martin Kosek]

Hello everyone!

It's been over a year now since we announced [1] that the Technical Writer
working on FreeIPA upstream guide [2] can no longer maintain the upstream
version of it. FreeIPA project developers wanted to carry the torch and forked
the outdated documentation in a new repository [3] and started the work on
reviving it again [4][5].

Unfortunately, over the past year it became apparent that despite several brave
contributors (special thanks to Gabe Alford and Martin Basti) helping with the
guide, the project simply does not have resources to develop both FreeIPA and
comprehensive documentation for it. The current FreeIPA guide is already way
behind the RHEL-7 downstream guides [6][7] maintained by a new Technical
Writer. In addition, old Fedora released documentation often pops up and
clobbers FreeIPA upstream documentation in search engine results. This needs to
change so that our users are not confused with obsolete information.

Writing documentation is enormous task in itself. Currently, until a team of
upstream Technical Writers joins the project to contribute alongside the
developers the only viable option is to stop maintaining and reviving the
upstream guide and keep only 2 main sources of documentation - design documents
and articles of FreeIPA.org community wiki, and downstream documentation, from
which the RHEL one [6][7] is the most complete. Upstream documentation tickets
would be closed or transferred into the downstream doc Bugzillas, existing
patches in [3] will be merged with the downstream RHEL documentation effort.

This is the proposal. What do you think? Is it a reasonable move? Does anyone
have time to be an upstream technical writer and carry the torch or should we
move on with this plan? A sustainable documentation effort is needed and
FreeIPA project is very much open to long term contributions.

We are looking forward to your feedback,
Your FreeIPA developers.


[1] https://www.redhat.com/archives/freeipa-users/2013-August/msg00044.html
[2]
http://docs.fedoraproject.org/en-US/Fedora/18/html-single/FreeIPA_Guide/index.html
[3] https://git.fedorahosted.org/cgit/freeipa-docs.git
[4] https://fedorahosted.org/freeipa/milestone/Revive%20FreeIPA%20guide
[5] https://fedorahosted.org/freeipa/milestone/FreeIPA%203.x%20Documentation
[6]
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Linux_Domain_Identity_Authentication_and_Policy_Guide/index.html
[7]
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Windows_Integration_Guide/index.html
[8]
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Linux_Domain_Identity_Authentication_and_Policy_Guide/ln-idp9643248.html

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