-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
Hi:
On 30 January 2013 00:29:47 pete wrote:
I've been reading the Feature discussions on devel@ today, and an idea came to mind. A process for documenting accepted Features would help prevent major changes from slipping through the cracks. Here's what I came up with so far; I think we can hammer it into something useful:
Good idea. I suggest we revise and formalize the beat-writers' workflow with a process that uses the feature pages.
Accepted Features[1] will be listed in a table roughly analogous to that used for Release Note Beats[2]. The table would have columns for the Feature name, a docs volunteer, and developer contact, as well as others reflecting the Feature documenting workflow.
I'm not sure we need another table. We already have developer contacts for many of the Release Notes beats. What we could do is revise the "Release Notes" and "Documentation" sections of the Feature page after a beat writer moves it into a particular beat, or a QA contact moves it into a particular Guide.
What other information did you imagine we would put in this table?
A set of guidelines for the docs volunteer covering a feature will come along with the table. The set of tasks to be juggled might include:
- Establishing an appropriate developer point of contact to aid in
documentation. Note that this isn't always the feature owner.
Between the existing developer contacts and the feature owner, do you think we will need another?
- Ensuring the content of the Feature is understandable by a
hypothetical average user.
This is something beat writers (should) already do. We saw in the F18 cycle that it's not necessarily the case, but a standardized workflow will help!
- Working up a basic guide to implementing the feature, if applicable.
In September, I wrote an email to the Docs QA list with a draft process to get features into applicable Guides.[1] I think we only partially did this for Fedora 18, and I don't remember any further developments in this area.
If you're suggesting a Release Notes supplement, where we describe how to use new features, that's something entirely different.
- Creating an entry for the Feature in the appropriate Release Notes
beat.
Beat writers.
- Checking existing guides for impact caused by the new Feature, filing
bugs as needed, and assisting the guide owners in updating as appropriate.
See above about QA contacts.
Also, the Release Notes QA contact (zogelsby) could check that all the Feature pages have been documented in the appropriate beat. Maybe he already does!
A defined process like this will help split up the workload caused by feature churn and cut redundant efforts by providing new information for multiple published works. Your thoughts?
As it stands, I think what we need most is more people who are both consistent across releases and have the time to do a good job. A clearly-defined working process will help beat-writers get on board in the first place, and remember what to do (and how easy it was!) when it comes time to repeat in the next cycle.
Christopher
[1] https://lists.fedoraproject.org/pipermail/docs-qa/2012- September/000103.html
On Tue, 2013-01-29 at 20:55 -0500, Christopher Antila wrote:
Hi:
On 30 January 2013 00:29:47 pete wrote:
I've been reading the Feature discussions on devel@ today, and an idea came to mind. A process for documenting accepted Features would help prevent major changes from slipping through the cracks. Here's what I came up with so far; I think we can hammer it into something useful:
Good idea. I suggest we revise and formalize the beat-writers' workflow with a process that uses the feature pages.
I don't have a problem with incorporating this into the beats workflow, per se. The main motivation for proposing it as a separate set of assignments and tasks were to solidify documenting Features as a Docs Project endeavor, not just a Release Notes endeavor. Ideally, the product of a feature writer would be usable in Guides as well as the Release Notes, essentially adding a check to the guides during each release. A separate process could either fragment our efforts or provide low handing fruit for new participants.
Accepted Features[1] will be listed in a table roughly analogous to that used for Release Note Beats[2]. The table would have columns for the Feature name, a docs volunteer, and developer contact, as well as others reflecting the Feature documenting workflow.
I'm not sure we need another table. We already have developer contacts for many of the Release Notes beats. What we could do is revise the "Release Notes" and "Documentation" sections of the Feature page after a beat writer moves it into a particular beat, or a QA contact moves it into a particular Guide.
What other information did you imagine we would put in this table?
Wrote example configs, checked guides, maybe. Placeholders for a process yet to be fleshed out.
A set of guidelines for the docs volunteer covering a feature will come along with the table. The set of tasks to be juggled might include:
- Establishing an appropriate developer point of contact to aid in
documentation. Note that this isn't always the feature owner.
Between the existing developer contacts and the feature owner, do you think we will need another?
In most cases, the feature owner would be the point of contact. By including this in the process, we are opening a channel of communication with the developers. More cooperation will in theory lead to higher quality documentation. Given the number of F18 features that had little, none, or inadequate information in the release notes section of their wiki page, it seems like a good idea to remind the feature owners about us early on.
- Ensuring the content of the Feature is understandable by a
hypothetical average user.
This is something beat writers (should) already do. We saw in the F18 cycle that it's not necessarily the case, but a standardized workflow will help!
Agreed. A well defined beats workflow is a good idea, whether or not it directly addresses features.
- Working up a basic guide to implementing the feature, if applicable.
In September, I wrote an email to the Docs QA list with a draft process to get features into applicable Guides.[1] I think we only partially did this for Fedora 18, and I don't remember any further developments in this area.
If you're suggesting a Release Notes supplement, where we describe how to use new features, that's something entirely different.
I'm proposing to draft your process into a new one :) We'd get roughly the same end result either way, but I suspect chunking the work up into small sets of tasks is easier to swallow. A new contributor might balk at the idea of checking every feature against every guide, but might accept volunteering to cover a single feature.
- Creating an entry for the Feature in the appropriate Release Notes
beat.
Beat writers.
- Checking existing guides for impact caused by the new Feature, filing
bugs as needed, and assisting the guide owners in updating as appropriate.
See above about QA contacts.
Also, the Release Notes QA contact (zogelsby) could check that all the Feature pages have been documented in the appropriate beat. Maybe he already does!
Fair point. I see QA as definitively reactive - valuable, of course, but reactive - where a feature patrol could be proactive. Still, the job gets done either way, and QA can happen at any time. I don't want to replace QA, just split up some of the work for easier distribution.
A defined process like this will help split up the workload caused by feature churn and cut redundant efforts by providing new information for multiple published works. Your thoughts?
As it stands, I think what we need most is more people who are both consistent across releases and have the time to do a good job. A clearly-defined working process will help beat-writers get on board in the first place, and remember what to do (and how easy it was!) when it comes time to repeat in the next cycle.
Christopher
[1] https://lists.fedoraproject.org/pipermail/docs-qa/2012- September/000103.html
Yes! More docs contributors would be great! I'll send some of my wife's bacon chocolate cupcakes to anyone who recruits new beat writers.
docs@lists.stg.fedoraproject.org
-
Christopher Antila -
Pete Travis