Docs Workflow-Discussion

Brian (bex) Exelbierd (https://lists.fedoraproject.org/pipermail/docs/2015-February/016037.html):

Our workflow needs to meet some goals:

• Infrequent contributors and drive-by contributors should have the easiest possible entry to the documentation process.
  • Pete Travis: We can enable truly drive-by submissions with mechanisms like concise, dedicated workflow documentation, bz or email templates, review queues, etc. Making fire-and-forget behavior more easy is a bonus of having an active community with a clearly established workflow, not something we should explicitly model the tooling and workflow to accommodate.
• 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.
  • Pete Travis: Some coverage of recommended methods would help out new contributors a lot.
• 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.

Steps

(cut n paste from https://lists.fedoraproject.org/pipermail/docs/2015-February/016037.html)

• Creation: The creation of new content or editing of existing content. Included in this step is any SME or language review.

Note this was separated from the Personas discussion here: [1]

• • Steps
    • Creation - self explanatory
    • 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.
  • 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.
  • Steps
    • 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
    • Staging - placement of completed and approved documentation for visual review
    • Publication - making completed and approved documentation available to consumers
  • Output: Content delivered to consumers.

• Internationalization: Translation and transformation for non-English speaking audiences.
  • Steps
    • Internationalization - self explanatory
    • Staging - Internationalized versions need to be able to be verified by a qualified person
    • Publication - this can use the same publishing mechanism as English
  • Output: Content delivered to consumers.