Hi Diana, I can only speak for myself, but this process seems a little bit over complicated as it involves many stages. We don't want to print a book, we only want good documentation. And I fear if we set up such strict rules, well, we don't get any docs anymore :)
I can live with your steps 1-3 and would change step 4 and 5: 4. Author sends docs as patch or commits it into scratchpad docs 5. Documentation Coordinator (or someone else) picks up doc, revises it and applies it to the documentation. Now I'm interested in the response :) Cheers Carsten Diana Shannon wrote: > > How will new docs, authored by Cocoon users, come to life? Here's my > current idea, along with some questions. Please, I *really* need your > input on this! I apologize if my past emails have been overly verbose. > I'm still learning how the community-based feedback model works for > initiatives such as this. > > Proposed process > 1. Author finds an irresistable "itch to scratch" regarding > documentation. > > 2. Author reads "How-To Write <document-type />". > > 3. Author consults topic status list (a web page on cocoon web site) to > make sure no other draft on this topic is in process. > > 4. Author proposes topic and document structure (how-to, tutorial, faq) > for new doc to <whom? /> > Question > - Does cocoon-dev want to review each and every topic proposed, or do > you want me/other document-oriented committers to handle topic > submissions? > - If this review is handled off-list, could we set up a generic email > alias (like [EMAIL PROTECTED])? Emails could be forwarded to one or > several committers, including myself, as well as stored? Don't we want > to ensure this process is not overly dependent on the responsiveness of > a single committer? > > 5. If topic approved, author drafts outline and sends to editor for > review. > > 6. Editor performs substantive and language edit. (Is the outline > coherent? Is the order of presentation logical? Does it follow the > suggested guidelines in document how-to? Is the language clear?) > > 7. Editor forwards outline to the SME (subject matter expert). > Question > - How do we match SMEs to documentation efforts, particularly for > advanced topics? Should the editor post the outline to cocoon-dev for > review by any interested/available developer/experienced user? Or should > individual SMEs indicate their interest to participate, when the topic > is first proposed? > > 8. SME reviews outline. > Note > The purpose of this oversight is to ensure technical accuracy and > adequate scope. In other words, I don't want the SME to assume any > concerns related to content editing, writing, or QA (quality assurance) > testing. As document coordinator, I'm going to try hard to enforce those > boundaries. Plenty of others within the Cocoon community can provide > non-SME skills. > > 9. Author writes draft document, based on revised/approved outline. > Author submits draft(s) to editor. > Question > - Is it ok for authors to contact SMEs as they are writing the document > or should they post questions to cocoon-dev? As we all know, developing > effective Cocoon solutions often requires knowledge of many different > topics. I think it may hard to find authors who have an in-depth > understanding of all substantive areas required to write a comprehensive > document. For example, one author may understand how to write a > generator but may need a few tips about logging. > > 10. Editor performs substantive (comprehensiveness), language (how ideas > are expressed), format (validation), and copy (spelling, grammar) edits. > Editor forwards relevant document sections to SME for review. > > 11. Author revises document as necessary. Author submits beta document > version. > > 12. Document QA testers perform usability tests. > > 13. Author revises as necessary. Editor/SME/Testers review as necessary. > > 14. Document committed. > Question > - To which branch? > > 15. Other commiters revise/fine tune, if necessary. > > 16. Author submits patches (or revised docs to document coordinator) > when updates are necessary. > > Thanks for *any* input. > > Diana > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, email: [EMAIL PROTECTED] > --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
