9:21 a.m.
I talked with randomuser about strategy moving forward. I have written up our
conversation in an interview style. The primary goal is to start some conversation around
these topics. Therefore:
YOUR HOMEWORK: Send an email back with the questions this raised for you
Our ulterior motive is to further inform our presentation at Flock.
---
To understand where we are going, we have to know where that is.
*What is the goal of the docs group and docs.fedoraproject.org?*
The docs group as having two basic, related goals: assisting developers, and assisting
users. Our current strategy does a reasonably thorough job of assisting users, but we
don't do as well with assisting developers, or new docs contributors, for that matter.
There's lots of new crazy code out there, and the large book strategy has a lot of
inertia and can feel stifling when it comes to new additions and rapidly changing areas.
*How do we fix this?*
The high-level solution is to enable developers and experienced users to write about
whatever they like to do. We would use a workflow that leverages the Docs Team's
greatest strength, experience. People can work with seasoned writers to produce very
high-quality work.
The biggest problem Docs contributors have is finding something to do, so that workflow
should provide a pipeline of requests working through clearly defined steps. a request
could be from a user ie https://bugzilla.redhat.com/show_bug.cgi?id=1229560 or from a
developer, ie the API reference discussion, or internally generated by the docs team as a
need for an upcoming release. The focus of this process should be on the quality of
content and the efficacy of addressing a specifically defined topic. Someone
shouldn't have to worry too much about markup or tools unless they've specifically
opted to work in a markup or with the tools.
This goes beyond just telling people, "You can write whatever you want however you
want and get help with the publishing." That's not enough. The scope of our
books is really too big to facilitate focused topical writing. The cookbook is evidence
of that; Randomuser has offered cookbook assistance to many people and few take the bait.
The new strategy is to build publishing/site generation tooling that supports varied
content. This way contributors can range from independently capable writers, to SMEs
looking to share but not learn the specifics of publishing, to requesters, to those
wanting to write but needing assistance to get there.
Ideally, we reach a point where each specialty group/SIG has a set of articles covering
their interests, in a format that they're able to maintain. The only real example of
that we have is the Amateur Radio Guide. And this is is basically single-handedly
maintained by jjmcd, despite there being many other Fedora contributors doing radio stuff.
This isn't ideal, but it is working for today. Rather than try to fix a working
process, let's try to get more folks on-board, for example the Astronomy SIG.
*How are we going to implement the solution?*
Implementation is a challenge. There are two aspects, **Community** and **Tooling**.
On the community side, We don't have a well conceived plan (other than sharing and
organic growth - which is slow and not guaranteed). This is critical as tools are not
valuable if no one uses them. We can't grow our docs if maintenance consumes all of
the folks involved.
With regards to tooling, we have lots of bright people and lots of ideas around tooling.
Tooling is solvable and being worked on. You can contribute to and follow the progress at
https://github.com/immanetize/anerist . But beforewarned, it could be be better
described.
*How do you envision the workflow for a new content change/addition?*
The system consists of a bunch of restricted commit repos containing large guides,
collections of ReST articles, whatever. When a change is committed to a repo the tooling
will see the commit and attempt to generate html from the affected files. If that
succeeds, (and hopefully if it passes some validation tests, the strings in Zanata
(Internationalization Tool) will be automatically updated to make the work available for
translation immediately. The tooling will also extract some metadata from the document
(title, subtitle, abstract, categorical information, etc.) and ultimately use that to
generate a stage version of the docs site for verification before publication.
An individual contribution comes in via a pull request workflow. This could be via a
pagure.io solution or via a traditional git clone solution. Pagure.io has the benefit of
bringing the fork/edit/PR process into a web-based format perfect for many contributors
and for drive-by contributors. The merge starts the process just mentioned.
Ideally we can support acls on a per branch and repository basis. This way a SIG, for
example, could have control of their specific documentation by merging PRs. Members of
the docs-writers group would have global commit capability. The branch structure can
resemble many popular open source projects with a master that is clean and release
branches for future maintenance. The system is branch-aware, so everything from
'master' goes to a draft area, things in f$n gets labeled as appropriate for f$n.
*What are our big blockers today?*
1. Community Outreach and Growth Plan.
2. Website redesign for docs.fedoraproject.org - it is stalled on some decisions around
older docs, etc.
3. Publishing is stalled on both design and the need to integrate legacy tools such as
publican in a new paradigm with other formats that use other tools. These need to all
roll to a common docs listing/Table of Contents.