Docs Workflow-Discussion

Workflow Ideas

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.

Publishing Tooling

At Flock 2015 there were two sessions of note for fedora-docs. The first was a presentation by randomuser and bexelbie on a way forward for docs. The second was a hacksession hosted by jsmith on how to make that way forward a reality. Here are some notes on that session. I am sure that something has been glossed over, so please reply with questions so we can suss out the additional details. Presentation: Media:organized_chaos_rw.odp

Our toolchain is designed to create an opportunity for new styles of contributions to the documentation. We have sketched out an architecture of git repositories, building/testing/deployment, and design needs. We are open to modifications, but are thinking of this structure (subject to debate/edit):

Team Ideas

• Git/Editing Team
  • Probably using Pagure, so this may mostly be confirming functionality/config
  • git repos are organized as master (rawhide) and branches for each release
  • Goals:
    • Git repos that have a web editor and interface option
    • Writers can fork a repo, then they write
    • Writers need to be able to build their version of the repo for preview (this should be able to be done via the same auto-publishing process)
      • Writers can send a PR to get their patch/change in
      • Changes are accepted by a more restricted group of contributors

• Build/Testing Team
  • We have some code using buildbot that needs to be "helped" and implemented
  • Today, testing is not well defined, but may be something like emender (think modular)
  • Probable publishing workflow
    • 1. Based on commit changes, rebuild the changed repo content to html
    • 2. Generate metadata to be used for the top-level menu/site generation
    • 3. Re-generate the top-level menu/site from the new source and existing unchanged sources
  • Goals:
    • Branches for each release are automatically built, tested and published based on a commit action
    • When content is committed to a release branch, it needs to automatically publish and push to Zanata for translation
    • Modular building of multiple markup formats need to be supported for building (docbook first)
    • Builds need to generate metadata for the overall site
    • Eventually we need to support builds of user forks for preview/testing
  • Translation Ideas
    • push new strings to Zanata on commits
    • allow for publishing of translations automatically

• Visual design and meta site builder Team
  • Design and Navigation and Concept help
  • CSS skinning for the entire site and all outputted html
  • build a menu/overview site to guide users to docs - input is the metadata files from each document/repo
    • Content validation ideas and solutions
    • Updating infra ansible.git to deploy buildbot on docs devices (and also still deploy buildbot for taskotron!)
    • CSS hacking
      • Build $MARKUP using common theme ^^CSS
      • Extracting metadata from ReStructuredText files
      • Assemble metadata from json, build menu (js?)
  • needs to be able to be rebuilt easily - static site generation?