Documentation Workflow Goals/Process [Was: Re: The State of Publishing Documentation in Fedora]

[Petr Kovar]

On Thu, 19 Feb 2015 14:20:56 +0100
"Brian (bex) Exelbierd" <bex at pobox.com> wrote:

> A Documentation Workflow
> 
> There is a lot of discussion going on around changing or replacing parts or all of the toolchain used for Fedora documentation.  Conversations like this are useful, however they seem to quickly become tool-only conversations.  I believe that in order to build an effective toolchain we have to all have a common belief in the goals that the toolchain will enable.  To that end, I'd like us to consider spending some time ensuring that we all think the work needs to be done the same way and to the same end.
> 
> To that end, I suggest we put this on the agenda for next Monday's docs meeting.
> 
> In the spirit of enabling people to edit, which is easier, than to create, I propose the following workflow idea.  As I mentioned above, this is deliberately not a tools based document.  Once we have agreement on what we want, we can then fit the tools into place that will create it.

Yes, I also agree that starting with workflow makes a lot of sense. 

> Our workflow needs to meet some goals:
> 
> - Infrequent contributors and drive-by contributors should have the easiest possible entry to the documentation process.
> - Users at every level should have the most flexibility possible in how they do their individual work.  This means that the minimum number of requirements are set.
> - Content that doesn't change from release to release should easily roll forward.  Content that does vary from release to release should be able to be easily segregated and maintained.  Content that has only minor variations from release to release should be able to easily be created across multiple releases.
> - When necessary content should be able to move quickly from creation to publication (i.e. CVEs).  However, the process should also easily support allowing content to be held for future releases or held indefinitely pending review/conversation/revision.
> - Documentation needs to be able to move cleanly from step to step in a process.  It should not be ambigious what content is in which step.  This also means that unfinished work should be segragated both from finished work and other unfinished work.
> - Each step should be optimized to have the least amount of friction for it's highest consumption users or to create patterns of desired behavior through friction reduction.
> - When a trade-off has to occur, complexity should be absorbed by the toolchain first and users in later steps second. This is based on the idea that there are fewer users impacted in later steps.
> - Internationalization should not be a blocker for the English language release.  Internationalization in one language shouldn't block another language.
> 
> These goals can be accomplished via the following steps.  To make things clean, I have grouped the steps into units that are able to be designed independently.  We will just need to define a firm input/output handoff.
> 
> - Creation: The creation of new content or editing of existing content.  Included in this step is any SME or language review.
>     - Steps
>         1. Creation - self explanatory
>         2. Review - an optional review by peers or SMEs for technical and language attributes.  We need to decide if we require this. I believe that we should request it of new writers but not of experienced writers.

Agreed. I'm in favor of not making the whole review process too formal as
this often gets in the way of easy entry for new or drive-by contributors.

>     - Output
>         An easily manageable set of content changes or additions that can be readily identified for processing in the next stage.
> 
> - Consensus: The decision about whether completed content is to be published and if so, for which version.  This is optional, however, I believe that we should have a small group of people who are empowered to move content to publication.  I do not believe every writer should have this ability.  I also don't think that this is the same as reviewing.  We can combine them, but that creates a lot of work for these people.

Right. We've had a FAS group for people with permissions to publish
content. I think we should keep that group around.

>     - Steps
>         1. Approval 
>     - Output
>         A clearly identifiable version of a document that consists of only publishable, complete content.
> 
> - Publication: Previewing content to verify it renders well and delivery to final location for usage by consumers.  This can theoretically be almost 100% automated.
>     - Steps
>         1. Staging - placement of completed and approved documentation for visual review
>         2. Publication - making completed and approved documentation available to consumers
>     - Output
>         Content delivered to consumers.

It would be sweet to have a working documentation stage in Fedora docs. I'm
unsure as to whether this stage should be completely segregated from the
published docs site, though. In GNOME docs, we use the same doc site to
deliver both the preview/devel and final versions of a document. By
default, the user is redirected to a stable version when navigating
through the site, e.g.:

https://help.gnome.org/admin/gdm/stable/

Only when they explicitly request a different version, they get a list of
previous/unsupported or devel versions of the doc:

https://help.gnome.org/admin/gdm/ 

> - Internationalization: Translation and transformation for non-English speaking audiences.
>     - Steps
>         1. Internationalization - self explanatory
>         2. Staging - Internationalized versions need to be able to be verified by a qualified person

I think this should too follow the same workflow as the English content.
This means we should make sure that the whole process is translator-friendly
too.

It would be good to reach out to translators and then decide whether we
want doc owners/maintainers to publish translated content or whether
translators should be part of that process.

>         3. Publication - this can use the same publishing mechanism as English
>     - Output
>         Content delivered to consumers.
> 
> I appreciate your feedback and look forward to a conversation.

These are some great ideas, thanks for sharing them, Brian. I think we
should put these on the wiki. I can create a page for that. Or maybe reuse
the one Pete already created?

Cheers,
pk