From: "Diana Shannon" <[EMAIL PROTECTED]>
> 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.
Hope this is shorter ;-P
> Proposed process
> 1. Author finds an irresistable "itch to scratch" regarding
> documentation.
Usually it's "users get angry at developers for not writing documentation
and go away slamming the door". ;-)
> 2. Author reads "How-To Write <document-type />".
Contributing -> documentation
> 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.
Or search on the aggregated titles page.
> 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?
I'd keep the process loose.
Just propose, get /quick/ feedback, and write it.
-1 for the mailing list. We did it for XSPs, and it was a complete failure.
Besides, we don't get that many offers for documentation ;-)
> 5. If topic approved, author drafts outline and sends to editor for
> review.
To you? Ok :-)
> 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?
Just post to dev and see reactions. If nobody complains, it's ok.
> 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.
Point 8 is sufficient.
> 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.
To the list. But of course the SME tries to reply himself.
> 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.
IMHO too much red tape.
Once the stuff is submitted and quickly reviewed by the SME, let's just
commit, and trim it later.
> Thanks for *any* input.
Maybe more concise still? ;-)
--
Nicola Ken Barozzi [EMAIL PROTECTED]
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
