Proposal for new docs workflow

[Pete Travis]

On 10/16/2015 02:24 PM, Paul W. Frields wrote:
> On Fri, Oct 16, 2015 at 11:18:34AM -0500, Pete Travis wrote:
>> 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, 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.
>
>

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 *everyone's* 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)

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.fedoraproject.org/pipermail/rel-eng/attachments/20151017/9e831f0d/attachment.html>