Proposal for new docs workflow

[Adam Miller]

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.

Thank you,
-AdamM


[0] - https://fedoraproject.org/wiki/ReleaseEngineering
[1] - https://fedoraproject.org/wiki/Category:Release_Engineering_SOPs?rd=ReleaseEngineering/SOP
[2] - https://en.wikipedia.org/wiki/ReStructuredText
[3] - http://sphinx-doc.org/
[4] - https://readthedocs.org/
[5] - https://fedora-fedmsg.readthedocs.org/en/latest/
[6] - http://autocloud.readthedocs.org/en/latest/
[7] - http://fedimg.readthedocs.org/en/stable/
[8] - http://nuancier-lite.readthedocs.org/en/latest/
[9] - http://libtaskotron.readthedocs.org/en/latest/
[10] - https://pagure.io/pagure/blob/master/f/doc
[11] - https://pagure.io/docs/pagure/
[12] - https://docs.pagure.org/pagure/