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

[Martin Kosek]

On 09/23/2014 05:06 PM, Martin Kosek wrote:
> 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
>

Hello list!

I did not see any further comments, objections or offers in this thread. In 
that case, we should then soon follow with the proposed path, i.e. to deprecate 
FreeIPA upstream guide and it's repository, publish upstream information on the 
FreeIPA.org wiki and have the full Guides managed only by (RHEL) downstream.

What we may do though is to publish a mirror of downstream RHEL guide git repo 
so that interested people can contribute to the downstream guide in form of 
patches and not just bug reports. I know that at least Gabe liked that idea.

Thanks,
Martin