Proposal for new docs workflow

[Paul W. Frields]

On Fri, Oct 09, 2015 at 03:32:15PM -0500, Adam Miller wrote:
> Hello all,
>     We currently have a lot of documentation in the Fedora Wiki[0][1]
> that is either old and out of date or just not relevant anymore and I
> know many people don't like to work in the wiki so I would like to
> make a proposal to change the documentation workflow so that we can
> improve the docs for ourselves and for potentially new community
> contributors who would like to join the fun.
> 
> I would first like to explain a couple options I have about Release
> Engineering documentation first.
> 
> I believe we should ultimately have two "types" of documentation for
> different roles that contributors would like to take on.
> 
> I think we can define this as "Rel-Eng Ops" and "Rel-Eng Tools Devs" such that:
> 
> Rel-Eng Ops are those who are doing the work to create composes,
> manage the infrastructure, the day to day operations, and the like.
> This is where the Standard Operating Procedures[1] for Fedora Release
> Engineering should live as well as an on-boarding guide for new
> community members who would like to know more about Fedora Rel-Eng
> and/or join the group and share in the work.
> 
> Rel-Eng Tools Devs are people who are going to be collaborating on
> release tools upstream such as pungi, mash, mock, koji, and others.
> These tools should each independently have their own documentation and
> test suites in order to describe how community developers who would
> like to contribute to these tools can do so. Things here that should
> be documented are common development workflows, tools that are used to
> make development/contribution easier, coding guidelines, contribution
> and pull request workflow guidelines, etc.
> 
> I think the tools themselves should be referenced in the SOPs or
> "Rel-Eng Ops" documentation in order to bridge those who are using the
> tools to the tools themselves as someone participating in one form of
> contribution (working on Ops tasks) may very well also participate in
> the other (contributing code to tools) or vice versa. I definitely
> don't want there to be any impression that these should be disjoint
> types of contribution/contributors but more so that they can stand on
> their own independently if someone out in the community who would like
> to contribute is more interested in one area versus the other.
> 
> Proposal:
> 
> I would like to start with the RelEng Ops documentation as it's the
> most "single point of entry", has a lot of docs that can be
> "translated" from the Wiki along with getting updates, and would be a
> good resource to have updated and documented in terms of the
> on-boarding of potential new contributors which could lead to interest
> in other tools that need individual documentation.
> 
> We would format all documentation using ReStructuredText[2] and
> sphinx-doc[3] as that is the defacto standard in the python community
> (which most of our tooling is written in), it's easy to use, and is
> already in use by the Fedora Apps, Infrastructure, and QA teams.
> (There are more example but I thought these were enough)
> 
> I propose these docs live in the releng pagure repository
> (https://pagure.io/releng) and possibly have a space on
> readthedocs.org[4] as it's already under heavy use with Fedora
> projects with docs written in rst/sphinx.[5][6][7][8][9]
> 
> We could alternatively use pagure itself for docs hosting as pagure
> hosts it's own docs also written in sphinx[10][11][12], it's not as
> automatic for rendering and would take a little bit of scripting but
> it's certainly an option.
> 
> If you've made it this far you get a cookie or something, but thank
> you for sticking with it.
> 
> I'm open to questions, comments, general feedback, and of course
> snide remarks.

Minor technical point, but do or Pierre think it's possible to
integrate readthedocs functionality with Pagure, such that a push to
your Sphinx docs would regenerate the site there?

Obviously readthedocs is itself FOSS so perhaps we could contribute a
patch for this upstream, since it seems like it's at least partly a
function of that site.


-- 
Paul W. Frields                                http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
  http://redhat.com/   -  -  -  -   http://pfrields.fedorapeople.org/
    The open source story continues to grow: http://opensource.com