-----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 -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.19 (GNU/Linux) iQIcBAEBAgAGBQJRCH2qAAoJEGpo1cWDqVnYYkYP/1PDfjqZDuqV/5qWvgVgxT/P TVJCw7p5SP1YUyNtKhDkXdikdm1iY+xIoUSCSgo5v5nHmP+4nex1pjBzQFdouYYA kS/leP71rHSZqg01t79i1inPzC9ukwtdEGwqeleBYHtQ/aWo273TJ9EWSzrb5n+t xeyWAnrDGdpZppIm0qIlXd2e9rAVFt1TMf4OeoSNzxeZGvBsZZnQXhzBRwcYdhu7 dm4B4HLCiFd7uTuT+HfSDvIC4U+Rthg5lwBRYay0JCYL9W/PXSqWx+heU3yApTsP 9gO7+vJRZ9/r4ljWph6mVpl2+9/S+xefu7JtVNCxgK4mjKkK2W/EMunymB98IFgi 57qS8rcIqpAWMo0KcS9DsLpuyxjq/cykkekwnef54AA0iKurREYC6tB+pgooIeNa MjkPdT7E99dewGPGXwTu1EqcJBvcuLkVUJKgC0vKXSeBXoPQvcVgXTfWD1WLAt6F q2d4WiTxunCzvrB0qLq51TTm8rGKKPDNweOQPWmcL3Hty7ok/vFrBqZAfnRt+I17 cPBm59CfpW2zNaCK2gWTX+S9y9sYe6UDTiewuPdSlbz38impynUiMYvcvidErsxR PtmJCIxz1Gg3R5cLW1C/rHJBcvhy/NmqCLKu+c2Gvo34TQgAjTo7+NEqEz34SaIM 2OsPbbjR92Om9+KeHUq/ =x1HS -----END PGP SIGNATURE----- -- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/docs
