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