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]
