cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <terrac...@mac.com>
Subject --- Help with document classification ---
Date Thu, 25 Apr 2002 19:05:27 GMT
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: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message