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.
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.
- 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
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.
- 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
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.
regards,
bex
--
docs mailing list
docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe:
https://admin.fedoraproject.org/mailman/listinfo/docs
