Fedora Docs Workflow and Publishing Improvement Project

Wed Jul 15 02:58:46 UTC 2015

So this makes me think of a question about guides.

If someone or a group make a guide that pertains to a version of Fedora, 
it becomes their responsibility to update and change it for future 
releases unless someone offers, gives assistance, or updates it on their 
own accord?

Is that a problem we have currently, when authors stop updating their 
guides for whatever reason?

Thank you,
-Glen

On 07/13/2015 05:57 AM, Brian (bex) Exelbierd wrote:
> Hi Sandra,
>
> I was traveling and took some time to get back to this.
>
>> On Jun 25, 2015, at 4:37 PM, Sandra McCann <scmccann2000 at gmail.com 
>> <mailto:scmccann2000 at gmail.com>> wrote:
>>
>> 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.
>
> There is a lot packed into this statement.  I agree that a "book 
> paradigm" creates ordering and topic curation.  A big fear of mine, 
> and it seems of yours, is that anything that is "article" based 
> becomes a kitchen utility drawer of disorder and chaos.  The knife you 
> want it always at the bottom and you know own 42 differently sized 
> grapefruit spoons because you either forget you have one or you can 
> never find them.
>
> I think that the key is that we can still have order and curation, but 
> we need to think about writing our topics in a more independent way. 
>  This is not a new thought and I am far from the first person to state 
> it here.  Perhaps what is needed is an assessment of what that really 
> means and a through review and modification of one group of topics 
> (aka book) to get it there and see if it works.
>
>> 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.
>
> The goal, as I understand it, is to have F22 material and F23 
> materials, for example, separated.  If something "rolls forward" 
> unmodified, let's have two copies.  git is pretty efficient so I am 
> not worried about disk space.
>
>> 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?
>
> Tagging can help here.  My response would be that the Astronomy SIG 
> should be doing two things: 1) Building a curated index/TOC of topics 
> for their materials and the related bits.  2) Adding specific topics 
> that are for their SIG.
>
> regards,
>
> bex
>
>
>>
>> Sandra
>>
>> On Mon, Jun 22, 2015 at 10:21 AM, Brian (bex) Exelbierd 
>> <bex at pobox.com <mailto:bex at 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?*
>>     <http://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 <http://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
>>     <http://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 at lists.fedoraproject.org <mailto:docs at lists.fedoraproject.org>
>>     To unsubscribe:
>>     https://admin.fedoraproject.org/mailman/listinfo/docs
>>
>>
>> -- 
>> docs mailing list
>> docs at lists.fedoraproject.org <mailto:docs at lists.fedoraproject.org>
>> To unsubscribe:
>> https://admin.fedoraproject.org/mailman/listinfo/docs
>
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.fedoraproject.org/pipermail/docs/attachments/20150714/2029b722/attachment.html>