Issue How should we classify Cocoon user documents to channel future content contributions -- from developers and users alike -- most effectively? What are the implications of such classifications on document structure, guidelines for contributors, and the Cocoon project's web site functionality?
Background We are all quite familiar with common classifications of online documents: FAQs, How-Tos, Tutorials, Guides, etc. Many open source projects vary greatly in how they interpret these terms. For example, one project's "FAQs page" serves as another project's "Manual". Other projects, lacking guidelines for authors, blur the distinction between documents types. For example, one project's "Concept" document may actually include an internal reference guide. After trial and error, "experienced" users learn to navigate their way to the information they need. Nevertheless, weak classification systems decrease, unnecessarily, the efficiency of problem solving and learning for all levels of users. Classification Proposal Before we start developing new documents for Cocoon, we need a well-defined document classification in place. I need your comments/criticism/advice on the classification structure proposed in detail below. Specifically: 1. Do you agree/disagree that we need each document type? 2. Do you agree/disagree with the scope/purpose of each type? Your input will guide my drafting of a series of "how-to author <document type name />" (which will probably mature -- someday -- into a more comprehensive author's guide). I need to complete these drafts *as soon as possible* so the increasing number of volunteer authors have the resources they need to contribute effectively. Current Goal My goal is to encourage the largest possible quantity of contributions, from different levels of users, without sacrificing quality. Some users may have enough knowledge/experience to author a helpful FAQ, but not necessarily enough time/detail/knowledge to author a more comprehensive "how-to". Other users may have a great snippet of code they'd like to share but lack adequate time to write a full-fledged guide or tutorial which utilizes the concept. In all these cases, users should *still* have a channel to contribute -- assuming the topic they want to address is valid. I believe technical and editorial review will provide sufficient quality assurance. Do you agree/disagree? IMHO, content fragmentation should not be a concern at this time, given this very early stage of the Cocoon documentation effort. As the documentation effort matures, I think it will be obvious which "FAQs" need to evolve into "How-Tos," which "How-Tos" need more elaborate treatment as "Guides", which specific types of contributions we should encourage/discourage, etc. To ensure accessibility, given the many forms of documentation proposed below, we may need to provide search/grouping/ToC functionality within some document types as well search functionality across all documentation types. Note Much of this classification effort was informed by Philip Rubens' (ed.) "Science and Technical Writing: A Manual of Style" (New York: Routledge, 2001). | ----- FAQ Document -----| Purpose Addresses holes or ambiguity in docs, bugs in code. Provides a quick (though not always the best) way to update docs. Frequency of use Specfic FAQ item tends to be read only once. Nature of Content Very narrow and specific scope. However, some content overlap (with other docs) is both necessary and unavoidable. Most answers will be short/concise but others may be longer. Potential Contributors All levels of users. Developers. Evolution/Lifetime Lifetime is variable. Some FAQs will eventually be migrated into other docs, e.g. guides and how-tos. Others will be eliminated by software and document updates. Architectural issues This document class might grow quickly. Shouldn't we treat specific FAQ content as separate documents? If so then we'll need a revised faq.dtd (as per Forrest) and stylesheet(s) as well as search/grouping functionality before the size grows unwieldy. Individual FAQs need "last modified" content. | ----- (Mini) How-To Document -----| Purpose Assists user in performing a task as quickly as possible. Describes a concise, procedural, action-oriented approach to a problem or task. Does not teach user a set of skills. (Note: this is similar to "mini-howtos" on Linux. For an analogy to the more elaborate Linux "howtos," see "Guide Document" below.) Frequency of use Once or twice, or until the knowledge/process is internalized. Nature of content Narrow scope. No content overlap with other how-tos. Variable length, depending on complexity of task. Potential Contributors Intermediate and advanced users. Developers. Evolution/Lifetime Lots of how-tos targetting variations on a single topic *may* reveal lack of sufficient treatment (of a pattern of problem solving) in a guide or tutorial. Proposed structure (not necessarily enforced by schema) 1. Introduction - overview - purpose - intended audience - requisite skills/configuration X. Body of how-to X. Related resources/documents | ----- Tutorial Document -----| Purpose Teaches a skill (or set of skills) through concept building, example, analogy, illustration. Imparts long-term, core knowledge/skills. Builds upon audience's existing conceptual framework (knowledge). Frequency of use Once, either in one sitting or over an extended period of time. Nature of content Essential, not peripheral, information related to tutorial topic, targetted at a specific audience (level of ability). Medium to long length. Builds concept/skill complexity gradually. Stresses repetition to reinforce learning. Has a critical sequence of procedures to aid learning. Provides recovery information for common errors. Written in engaging, motivating tone to encourage user. Potential Contributors Intermediate and advanced users. Developers. Evolution/Lifetime Long lifetime. Proposed structure (not necessarily enforced by schema) 1. Introduction - overview - purpose - level of difficulty (newbie, intermediate, advanced) - intended audience - requisite skills/configuration X. Tutorial Content (includes conceptual model, examples, analogies, how-tos) X. Related resources/documents | ----- Examples/"Cookbook" Recipes Document -----| Purpose Illustrates multiple/alternative approach(es) to problem solving. Provides a mix of conceptual/practical knowledge. Could reveal design principles or "best practices" approaches. Designed to reinforce knowledge gained in other documents. Provides accessible, immediately applicable examples of solutions for web development needs. Frequency of use Once, unless interactive discussions added (later). Nature of content Narrow scope. Short to medium length. Informal tone. Potential Contributors Intermediate and advanced users. Developers. Evolution/Lifetime Variable lifetime, based on relevancy of topic. Proposed structure (not necessarily enforced by schema) 1. Overview 2. Recipe/Snippet/Code 3. Explanation/discussion | ----- Guide Document -----| Purpose Provides comprehensive, in-depth treatment of a high-order task (e.g. installing/building C2 on multiple platforms), Cocoon component (such as portal, slash-edit, etc.), or concern (e.g. performance). Frequency of use Repeatedly, until information is committed to memory. Nature of Content Comprehensive content scope within subject matter. Medium to long length. May include conceptual, procedural, as well reference information. May address different levels of abilty within audience. Potential Contributors Intermediate and advanced users. Developers, particularly component developers. Evolution/Lifetime Long lifetime. Architectural issues - contributions may require sub-sitemap Proposed structure (not necessarily enforced by schema) 1. Table of contents 2. Introduction - overview - purpose - intended audience - requisite skills/configuration X. Guide Content X. Related resources/documents | ----- Case Study Document -----| Purpose Provides "real world" information, instruction, and insight the capabilities of Cocoon. Serves as "success story" for promoting/selling Cocoon to management/developers. Helps users to evaluate and apply Cocoon-based solutions. Provides meaningful background information about "live sites." Frequency of use Probably once. Nature of Content Medium to long length, depending on sophistication of Cocoon solution. Informal, narrative style. Should be instructive/insightful for community, not simply a promotional piece for the web site/developer. Potential Contributors All levels of users. Evolution/Lifetime Long lifetime. Proposed structure (not necessarily enforced by schema) X. Case Study Content | ----- Concept Document -----| Purpose Provides visual, "big picture" overview information about a topic. Frequency of use Probably once. Nature of Content Medium to long length. Informal, narrative style. Strategic use of pictures, tables, lists. May include discussion of theoretical models, analogies, examples. May persuade audience to "do something" (read more, use Cocoon, etc.). Potential Contributors Developers like Stefano, most likely. Intermediate and advanced users. Evolution/Lifetime Long lifetime. Could be migrated into other guides. Proposed structure (not necessarily enforced by schema) 1. Introduction - overview - purpose - intended audience X. Concept Content X. "Find out more" documents/references | ----- Reference Document -----| Purpose Provides encyclopedic information. Frequency of use Repeatedly. Nature of Content Highly dynamic content. Long overall length, but limited vocabulary within reference item detail. Assumes audience has some familiarity with subject matter. Potential Contributors Developers. Evolution/Lifetime Long lifetime. Architectural issues - automation through custom components Proposed structure (not necessarily enforced by schema) 1. ToC 2. Reference Content 3. Index X. Other navigational aids Thanks for reading! Diana --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
