On 02/26/2015 11:11 AM, Petr Kovar wrote: > On Thu, 19 Feb 2015 14:20:56 +0100 > "Brian (bex) Exelbierd" <bex@xxxxxxxxx> 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. > +1000, thanks for starting the conversation. Although, I don't know that I'll be able to *completely* abstract tooling from my thinking on the subject... I've been focusing the discussion on tooling lately because conversations about process have often been to abstract to result in something actionable, but in this case, I like where you're steering it :) >> Our workflow needs to meet some goals: >> >> - Infrequent contributors and drive-by contributors should have the easiest possible entry to the documentation process. I agree with this in spirit, but there's a tradeoff here, both in content quality and the contributor's sense of ownership and participation. 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. No argument here. That said, some coverage of recommended methods would help out new contributors a lot. (Here's how you create a publican book, here's how you create a ReStructuredText article, this is how I set up my editor.) Writing style might also fall into this category; I'd rather spend more time and coach people away from passive voice writing, excessive transitional prose, etc, and readers would benefit from our following some basic conventions [to be [re]defined?] >> - 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. This has come up a few times. I don't see any problem with having content dissociated from the release cycle, as long as it's suitable for that, there's a clear commitment for maintenance, and the tooling supports it. This should not enable outdated documentation to have the same presence as current documentation, even if there's nothing current on the topic. >> - 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 would go in the tooling requirements column, mostly. >> 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 State tracking would need both process and tooling changes to support a defined incubation workflow. It sounds nice, especially for communicating to the group where we need work, but for many cases I worry this might be introducing unwarranted process and additional complexity for contribution. I think we should go forward with creating a documentation life cycle plan as part of the workflow effort, but keep it *very simple*. Progressing from one stage to the next, presuming viable content, shouldn't require more than a brief irc or list conversation. The tooling I have in mind - and I *am* working on it - should be capable of creating a draft site as well as the 'production' site. I have ideas to share here, but don't want to distract the thread. Mostly, they depend on using git... Our side of the localization process ( pushing POs to Zanata, pulling POs from Zanata ) can be entirely automated. If we want only reviewed strings, we can probably configure the zanata client to only pull reviewed strings; it's up to each language's team to review the translations. FYI, it's optional on the platform, and many or most language teams have opted not to use the string approval features. If you're talking about automated commits of strings only if they build, that can be automated too. Let's do use https://fedoraproject.org/wiki/Docs_Project_Focus for expanding on these ideas as well. It can be cleaned up later if need be, but for now we'll have one place to look. -- -- Pete Travis - Fedora Docs Project Leader - 'randomuser' on freenode - immanetize@xxxxxxxxxxxxxxxxx -- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/docs
