You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Diana Shannon <te...@mac.com> on 2002/04/25 21:05:27 UTC
--- Help with document classification ---
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
Re: tracks/titles [was: Re: --- Help with document classification ---]
Posted by David Crossley <cr...@indexgeo.com.au>.
Diana Shannon wrote:
> Bertrand Delacretaz wrote:
>
> > 1) Tracks:
> > it might be worthwile at some point to create "tracks" into the
> > documentation, task-oriented reading guides.
> >
> > For example: if you want to publish static XML to HTML, here's your
> > reading
> > list: "FAQ 232, FAQ 321, html publishing how-to, site navigation guide"
>
> Do you think these need separate classification, or should they be
> how-tos (with links to other how-tos), categorized as tracks?
Sounds like a separate class of document. I wonder if
this is an application of XML Topic Maps (XTM) ... of which
i know nothing about ... just fascinated by their possibilities,
and Cocoon is the perfect place to implement them.
TopicMaps were briefly discussed recently on Forrest-dev.
http://marc.theaimsgroup.com/?l=forrest-dev&m=101647290524645
> > 2) Master of the Titles:
> > Document names/titles (and their consistency) are sooo important IMHO to
> > guide the user to the right place, I think the main title of every
> > document
> > should be reviewed by the community or by a designated "Master of the
> > Titles"
> > before publishing the document.
>
> What if we also added a one-sentence description of the piece, along
> with title and last modified date, to be returned with search results?
I agree with Bertand that the Titles of all documents need to
be carefully reviewed. They are the most important part of the
document. At the organisation that i worked with when the WWW
first hit the scene, i wrote applications that automatically pestered
people if they did not properly utilise <title> in their HTML.
Until recently there was a problem in Cocoon whereby the
space available for a title was limited. This was because
Cocoon was showing off with banner-image generation
which meant that only short titles could be used. This would
have had a massively detrimental effect on the quality of
document titles. Now that we have plain-text banners, we
can return to more descriptive titles.
Well-spotted, Bertrand. The documentation review needs to
have this as a specific task - generate a list of all current
titles and review them.
--David
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: tracks/titles [was: Re: --- Help with document classification ---]
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Friday 26 April 2002 11:19, Diana Shannon wrote:
>. . .
> Do you think these need separate classification, or should they be
> how-tos (with links to other how-tos), categorized as tracks?
>. . .
I see the tracks as part of the navigation, which could be:
a) search-based ("googling through the docs")
b) track-based ("what do you want to study")
c) document-type based ("faqs", "guides", etc.)
In this view tracks documents are orthogonal to the rest of the
documentation, so yes, a separate classification.
Either there are "tracks" XML documents that point to other docs and need to
be properly maintained, or (parts of?) documents that need to be included in
a track contain attributs like
<belongs-to-track track-name="html-publishing" chapter="intro"
position="250"/>
Where position is a relative ID used to sort the document when creating the
track.
>. . .
> What if we also added a one-sentence description of the piece, along
> with title and last modified date, to be returned with search results?
>. . .
Certainly useful, but the "official document names" are very important IMHO
so that the user knows what is what.
-Bertrand
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
tracks/titles [was: Re: --- Help with document classification ---]
Posted by Diana Shannon <te...@mac.com>.
On April 26, 2002, Bertrand Delacretaz wrote:
Very helpful comments, Bert.
> 1) Tracks:
> it might be worthwile at some point to create "tracks" into the
> documentation, task-oriented reading guides.
>
> For example: if you want to publish static XML to HTML, here's your
> reading
> list: "FAQ 232, FAQ 321, html publishing how-to, site navigation guide"
Do you think these need separate classification, or should they be
how-tos (with links to other how-tos), categorized as tracks?
>
> 2) Master of the Titles:
> Document names/titles (and their consistency) are sooo important IMHO to
> guide the user to the right place, I think the main title of every
> document
> should be reviewed by the community or by a designated "Master of the
> Titles"
> before publishing the document.
What if we also added a one-sentence description of the piece, along
with title and last modified date, to be returned with search results?
Diana
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: --- Help with document classification ---
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Great work Diana, your plan looks really cool to me!
There are two additions that I'm thinking of:
1) Tracks:
it might be worthwile at some point to create "tracks" into the
documentation, task-oriented reading guides.
For example: if you want to publish static XML to HTML, here's your reading
list: "FAQ 232, FAQ 321, html publishing how-to, site navigation guide"
2) Master of the Titles:
Document names/titles (and their consistency) are sooo important IMHO to
guide the user to the right place, I think the main title of every document
should be reviewed by the community or by a designated "Master of the Titles"
before publishing the document.
m2c
-Bertrand
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: --- Help with document classification ---
Posted by Diana Shannon <te...@mac.com>.
On Friday, April 26, 2002, David Crossley wrote:
>
>> | ----- FAQ Document -----|
>>
>> Purpose
>> Addresses holes or ambiguity in docs, bugs in code.
>
> Has many pruposes. Also is something that gets asked frequently.
> Some things are so fundamentally hard to grasp, or so commonly
> misunderstood. This is not due to deficiency in any doco. This
> type of FAQ remains forever.
>
>> Provides a quick
>> (though not always the best) way to update docs.
>
> I am not sure what you mean here.
Well, sometimes it's more expedient to add an extra FAQ item than it is
to edit an existing how-to, guide, etc.
>> 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.
>
> The non-usability of the long FAQ as one single document
> with Cocoon 1 was a real turn-off. I got frightened when i saw
> the state of that document.
>
> Are you suggesting a separate document for each Question?
Yes.
> Sounds interesting. In that way, FAQ listings could be drawn
> together to form various topics.
Potentially, if managed carefully. In other words, I wouldn't want to
encourage lots of some tangential FAQ contributions for the sole purpose
of filling holes in desired topic tracks/maps. Have you seen this
implemented anywhere?
Diana
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: --- Help with document classification ---
Posted by David Crossley <cr...@indexgeo.com.au>.
> | ----- FAQ Document -----|
>
> Purpose
> Addresses holes or ambiguity in docs, bugs in code.
Has many pruposes. Also is something that gets asked frequently.
Some things are so fundamentally hard to grasp, or so commonly
misunderstood. This is not due to deficiency in any doco. This
type of FAQ remains forever.
> Provides a quick
> (though not always the best) way to update docs.
I am not sure what you mean here.
> 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.
All should link directly to further info.
> 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.
The non-usability of the long FAQ as one single document
with Cocoon 1 was a real turn-off. I got frightened when i saw
the state of that document.
Are you suggesting a separate document for each Question?
Sounds interesting. In that way, FAQ listings could be drawn
together to form various topics.
--David
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org