Proposal for new docs workflow

[Pete Travis]

On Oct 16, 2015 10:14 AM, "Paul W. Frields" <stickster at gmail.com> wrote:
>
> 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

FWIW, the thing I'm putting together for docs.fp.o is intended to support
continuous delivery of documentation from git repos full of rst files.  I
don't know if you want to wait for it, but when ready, we can simply add
some metadata to the articles (I did this for infra-docs already) and plug
the repo into the system.

--Pete
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.fedoraproject.org/pipermail/rel-eng/attachments/20151016/c3dd9226/attachment.html>