9:37 a.m.
The first question that comes to mind is how do these individual articles
combine/link into a cohesive whole? While I'm not in love with the book
paradigm, it does take care of that logical grouping and flow from one
topic/article to another.
And how do these articles handle release to release variations, or will
some background magic pull them into an F23 specific section or an F22
specific section etc.
I guess my worries are from the end user perspective. How will I know what
I can do with astronomy and Fedora, and be sure I've found all the content
vs select articles?
Sandra
On Mon, Jun 22, 2015 at 10:21 AM, Brian (bex) Exelbierd <bex(a)pobox.com>
wrote:
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.
--
docs mailing list
docs(a)lists.fedoraproject.org
To unsubscribe:
https://admin.fedoraproject.org/mailman/listinfo/docs