<html>
<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<br>
<br>
<div class="moz-cite-prefix">On 10/16/2015 02:24 PM, Paul W. Frields
wrote:<br>
</div>
<blockquote cite="mid:20151016192433.GN26492@raquel-eth.redhat.com"
type="cite">
<pre wrap="">On Fri, Oct 16, 2015 at 11:18:34AM -0500, Pete Travis wrote:
</pre>
<blockquote type="cite">
<pre wrap="">On Oct 16, 2015 10:14 AM, "Paul W. Frields" <a class="moz-txt-link-rfc2396E" href="mailto:stickster@gmail.com"><stickster@gmail.com></a> wrote:
</pre>
<blockquote type="cite">
<pre wrap="">
On Fri, Oct 09, 2015 at 03:32:15PM -0500, Adam Miller wrote:
</pre>
<blockquote type="cite">
<pre wrap="">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"
</pre>
</blockquote>
</blockquote>
<pre wrap="">such that:
</pre>
<blockquote type="cite">
<blockquote type="cite">
<pre wrap="">
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
(<a class="moz-txt-link-freetext" href="https://pagure.io/releng">https://pagure.io/releng</a>) 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.
</pre>
</blockquote>
<pre wrap="">
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
</pre>
</blockquote>
<pre wrap="">
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.
</pre>
</blockquote>
<pre wrap="">
Pete, might be going OT for this list, in which case we can go
elsewhere, but how does that differ from readthedocs? I'm curious
what's missing there that might affect other places our team's using
it.
</pre>
</blockquote>
<br>
<pre wrap="">Readthedocs gives you one site per resource, so you'd have ie
fedora-releng.readthedocs.org as one big book about fedora's release
engineering . I want to present many resources in a browseable way, so
this will also generate category pages, navigation structure, etc. The
goal is to put things like releng, apps, infra, qa docs in one place
where they can interlink, along with user facing docs of all types. The
goal is to offload <b class="moz-txt-star"><span class="moz-txt-tag">*</span>everyone's<span class="moz-txt-tag">*</span></b> publishing and formatting work to one
place, so you really only have to worry about content.
-- Pete
(reply to all fail, sorry for the noise, Paul)
</pre>
</body>
</html>