documentation architecture?

[Diana Shannon <te...@mac.com>]

Is it within the scope of Forrest to offer projects suggested 
mechanisms/approaches/templates/schema for documentation? For example, 
let's say a project had the following documentation offerings.

documentation categories
- FAQs
- mini how-tos
- guides (e.g., component-oriented)
- tutorials
- examples/cookbook "recipes"
- case studies
- reference guides
- quick-reference guides

For example, you may want to have:
- "What's New" page within each documentation category
- "Features" page (any document category)
- Ability to search/browse within each documentation category as well as 
across all documentation categories, based on content, last modified 
date (thanks David Crossley).
- Dataset scalability mechanism (e.g., when number of how-tos files 
grows too large)
- Contributor's info (instructions/info, author/edit guidelines, 
how-tos, schema)

Also, does Forrest's FAQ dtd (with all FAQ elements in a single file) 
properly anticipate processing/administering large numbers of FAQs, 
particularly when you factor in potential community contributions?

Is it within the mission of Forrest to implement/provide these items? If 
not, I apologize for the noise.

Thanks.

Diana

Re: FAQ [was: Re: documentation architecture?]

[Diana Shannon <te...@mac.com>]

On April 26, 2002, Steven Noels wrote:

> My remaining emotion about this opposing-views-discussion is that I'm
> perfectly willing to massage DTD's into whatever direction we would
> like, but that we should decide on the 'when': we have legacy, but if we
> can convince more people to use Forrest because of the ease of
> information entry, and we have to change DTD's for that purpose, I'm
> perfectly happy.

Is it a Bad Thing to offer legacy as well as "new and improved" dtds? If 
Forrest provides tools for people to adapt their legacy content (to work 
with the new DTDs) would that still discourage Forrest adoption?

What if we kept the existing FAQ dtd and had multiple instances of FAQ 
data files, one per FAQ category?

> With regards to Literate Programming (i.e. Javadoc as a starter for
> 'human' documentation): I'm not convinced this is the ideal approach...
> the Cocoon documentation is in abysmal state partly because of the lack
> of 'connecting' documents, which provide a flow in between the
> component-based documentation snippets...

I agree, *none* of this works when so many content holes remain. Should 
we remedy the solution by reusing    and improving the content that 
exists or seek out more contributions?  One might believe -- given this 
thread of reusing documentation snippets -- that we have a scarcity of 
authors.  IMHO we don't have a scarcity of authors, simply inefficient 
mechanisms to encourage/capture their contributions. I think the greater 
number and variety of authors, the more effective the documentation 
effort will be for an open source project. It will be even better if 
content overlaps somewhat. Why? Open source developers typically 
introduce new conceptual models in their work. Many features of new 
releases remain underutilized by users -- even when some preliminary 
documentation exists for it. I think a diversity of voices/authors, each 
expressing an interpretation/application of this or that feature, is 
central to the community as whole in being able to grok these new 
conceptual models. This exchange occurs to some extent on the user 
lists, but it's generally incomplete, fragmented, and difficult to 
access. Our ability to tap into this community resource, and channel it 
(to the benefit of other users) into more meaningful document 
structures, is crucial.

How to do this? An early project, like POI, may need only a single 
"contribution" page. A more advanced project may need a whole section of 
pages and tools, with instructions and resources for community authors 
(similar to what I'm developing for Cocoon). Forrest could provide both 
sets of resources and leave it up to each project to decide what 
pages/tools to deploy and when...

Diana

RE: FAQ [was: Re: documentation architecture?]

[Steven Noels <st...@outerthought.org>]

Hi folks,

I've been away for a few days, and catching up...

I have some real-life experience setting up modular DTD's where UOI's
(Units of Information) are being assembled into 'consumable' documents:
while the result can be great, the burden it places on the shoulders of
the document editor mut not be underestimated.

Prior suggestions to tweak the DTD's have been opposed because of
'legacy' reasons... we indeed should not underestimate the amount of
available documentation already in xdoc format.

My remaining emotion about this opposing-views-discussion is that I'm
perfectly willing to massage DTD's into whatever direction we would
like, but that we should decide on the 'when': we have legacy, but if we
can convince more people to use Forrest because of the ease of
information entry, and we have to change DTD's for that purpose, I'm
perfectly happy.

With regards to Literate Programming (i.e. Javadoc as a starter for
'human' documentation): I'm not convinced this is the ideal approach...
the Cocoon documentation is in abysmal state partly because of the lack
of 'connecting' documents, which provide a flow in between the
component-based documentation snippets...

Just some thoughts while I'm catching up,

</Steven>

> -----Original Message-----
> From: Nicola Ken Barozzi [mailto:nicolaken@apache.org]
> Sent: donderdag 25 april 2002 22:11
> To: forrest-dev@xml.apache.org
> Subject: Re: FAQ [was: Re: documentation architecture?]
>
>
> From: "Diana Shannon" <te...@mac.com>
>
> >
> > On Thursday, April 25, 2002, Robert Koberg wrote:
> >
> > >>
> > >> As you see, the *same* piece of information is conveyed
> in different
> > >> ways.
> > >> The *same*, no need to rewrite anything.
> > >>
> > >> On this list I haven't yet seen Diana say this, correct me if I'm
> > >> wrong.
> > >>
> > >
> > > Maybe I am wrong, but I thought the whole premise of XML
> was resuable
> > > content abstracted from the presentation. I assumed this
> was a given,
> > > where it is appropriate. But, you should not try to fit
> square pegs
> > > into round holes.
> >
> > Ken, while you may be able to do this from a technological
> standpoint,
> > just how much value does it add to the user/reader
> experience? Think how
> > oppressive the style guide would have to be. Your "content
> blocks" would
> > have to be unbearably monotone so that they could fit into
> any document
> > context. This might work well for snippets of reference guides (with
> > notoriously volatile timestamps) as discussed recently on
> cocoon-dev.
> > However, I'd worry, in other cases, that you'd dampen the
> rich range of
> > styles and tones authors employ when writing by forcing them to
> > incorporate "official" content within their own works.
> >
> > Sometimes it's helpful to hear someone else say the same
> thing -- a bit
> > differently.
>
> Gee, I was starting to think that I was talking a different
> language ;-)
> I think you got my point :-)
>
> I see your point, but being programmer, I have the preconception that
> duplicating code is bad. That's why I *love* javadocs,
> because they put the
> information where it lives, and *only* there, in one place.
>
> I'll think about it a bit more.
>
> --
> Nicola Ken Barozzi                   nicolaken@apache.org
>             - verba volant, scripta manent -
>    (discussions get forgotten, just code remains)
> ---------------------------------------------------------------------

Re: FAQ [was: Re: documentation architecture?]

[Nicola Ken Barozzi <ni...@apache.org>]

From: "Diana Shannon" <te...@mac.com>

>
> On Thursday, April 25, 2002, Robert Koberg wrote:
>
> >>
> >> As you see, the *same* piece of information is conveyed in different
> >> ways.
> >> The *same*, no need to rewrite anything.
> >>
> >> On this list I haven't yet seen Diana say this, correct me if I'm
> >> wrong.
> >>
> >
> > Maybe I am wrong, but I thought the whole premise of XML was resuable
> > content abstracted from the presentation. I assumed this was a given,
> > where it is appropriate. But, you should not try to fit square pegs
> > into round holes.
>
> Ken, while you may be able to do this from a technological standpoint,
> just how much value does it add to the user/reader experience? Think how
> oppressive the style guide would have to be. Your "content blocks" would
> have to be unbearably monotone so that they could fit into any document
> context. This might work well for snippets of reference guides (with
> notoriously volatile timestamps) as discussed recently on cocoon-dev.
> However, I'd worry, in other cases, that you'd dampen the rich range of
> styles and tones authors employ when writing by forcing them to
> incorporate "official" content within their own works.
>
> Sometimes it's helpful to hear someone else say the same thing -- a bit
> differently.

Gee, I was starting to think that I was talking a different language ;-)
I think you got my point :-)

I see your point, but being programmer, I have the preconception that
duplicating code is bad. That's why I *love* javadocs, because they put the
information where it lives, and *only* there, in one place.

I'll think about it a bit more.

--
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------

Re: FAQ [was: Re: documentation architecture?]

[Diana Shannon <te...@mac.com>]

On Thursday, April 25, 2002, Robert Koberg wrote:

>>
>> As you see, the *same* piece of information is conveyed in different 
>> ways.
>> The *same*, no need to rewrite anything.
>>
>> On this list I haven't yet seen Diana say this, correct me if I'm 
>> wrong.
>>
>
> Maybe I am wrong, but I thought the whole premise of XML was resuable 
> content abstracted from the presentation. I assumed this was a given, 
> where it is appropriate. But, you should not try to fit square pegs 
> into round holes.

Ken, while you may be able to do this from a technological standpoint, 
just how much value does it add to the user/reader experience? Think how 
oppressive the style guide would have to be. Your "content blocks" would 
have to be unbearably monotone so that they could fit into any document 
context. This might work well for snippets of reference guides (with 
notoriously volatile timestamps) as discussed recently on cocoon-dev. 
However, I'd worry, in other cases, that you'd dampen the rich range of 
styles and tones authors employ when writing by forcing them to 
incorporate "official" content within their own works.

Sometimes it's helpful to hear someone else say the same thing -- a bit 
differently.

Diana

Re: FAQ [was: Re: documentation architecture?]

[Robert Koberg <ro...@koberg.com>]

Nicola Ken Barozzi wrote:

>From: "Robert Koberg" <ro...@koberg.com>
>Maybe I haven't explained myself well enough, but I *did* refute this in
>what I wrote.
>Not that here vision is not sensible, I'm just trying to bring the
>documentation system of a project further than "a book online".
>

I have seen nothing from her about a book online.

>
>
>Diana seems to be talking about different sections that each give an extra
>contribute to the docs.
>
>"address holes in the documentation" means that the FAQ contains information
>that is not in the general documentation, which implicitly has "holes".
>
>Also: "However, over time, I think FAQ
>content should migrate to more appropriate document types: how-tos,
>guides, tutorials. ", which in means that the FAQ is a sort of
>well-organized forum.
>
this makes perfect sense. But i see you concern now after reading the 
thread. I see the FAQ as one entry point to more documentation

>
>
>What I envision instead is that ALL the documentation can be seen and read
>in different ways, different views.
>
I just assumed this is the way it would be...

>
>
>For example, let's say that in the docs there is a paragraph about how to
>install Cocoon on Weblogic.
>There could be a question in the FAQ that says "how do I install Cocoon on
>weblogic?".
>Or in the tutorial: "Now install Cocoon. If you have weblogic...".
>
OK, sure. Or it could easily be a link. Whichever makes more sense. I 
would think a summary (taken from the main docs) and a link to further 
info would make more sense because it takes them out of a chaotic 
environment and brings them to an area that deals with specific needs.

>
>
>As you see, the *same* piece of information is conveyed in different ways.
>The *same*, no need to rewrite anything.
>
>On this list I haven't yet seen Diana say this, correct me if I'm wrong.
>

Maybe I am wrong, but I thought the whole premise of XML was resuable 
content abstracted from the presentation. I assumed this was a given, 
where it is appropriate. But, you should not try to fit square pegs into 
round holes.

>
>
>>Everything you describe below has already been described by Diana??
>>
>
>Is this a question?
>I don't think Diana needs to be helped, she is more than able to speak for
>herself, thank you.
>

Whatever... I was helping myself because I agree with her approach...

best,
-Rob

Re: FAQ [was: Re: documentation architecture?]

[Nicola Ken Barozzi <ni...@apache.org>]

From: "Robert Koberg" <ro...@koberg.com>

> It sounds like you just restated what she is trying to do.

Dunno, I'm trying to convey something new, but if it's already said then
even better, I'm +1 with it ;-)

> Nicola Ken Barozzi wrote:
>
> >From: "Diana Shannon" <te...@mac.com>
> >
> >>IMO, FAQ content should primarily address holes or ambiguity in other
> >>documentation, as well as bugs in code.
> >>
> >
> >Not necessarily.
> >
>
> Where do you go on to refute this? She seems to be right on with
> everything she has proposed so far.

Maybe I haven't explained myself well enough, but I *did* refute this in
what I wrote.
Not that here vision is not sensible, I'm just trying to bring the
documentation system of a project further than "a book online".

Diana seems to be talking about different sections that each give an extra
contribute to the docs.

"address holes in the documentation" means that the FAQ contains information
that is not in the general documentation, which implicitly has "holes".

Also: "However, over time, I think FAQ
content should migrate to more appropriate document types: how-tos,
guides, tutorials. ", which in means that the FAQ is a sort of
well-organized forum.

What I envision instead is that ALL the documentation can be seen and read
in different ways, different views.

For example, let's say that in the docs there is a paragraph about how to
install Cocoon on Weblogic.
There could be a question in the FAQ that says "how do I install Cocoon on
weblogic?".
Or in the tutorial: "Now install Cocoon. If you have weblogic...".

As you see, the *same* piece of information is conveyed in different ways.
The *same*, no need to rewrite anything.

On this list I haven't yet seen Diana say this, correct me if I'm wrong.

> Everything you describe below has already been described by Diana??

Is this a question?
I don't think Diana needs to be helped, she is more than able to speak for
herself, thank you.

--
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------

Re: FAQ [was: Re: documentation architecture?]

[Robert Koberg <ro...@koberg.com>]

Hi,

It sounds like you just restated what she is trying to do.


Nicola Ken Barozzi wrote:

>From: "Diana Shannon" <te...@mac.com>
>
>>IMO, FAQ content should primarily address holes or ambiguity in other
>>documentation, as well as bugs in code.
>>
>
>Not necessarily.
>

Where do you go on to refute this? She seems to be right on with 
everything she has proposed so far.

Everything you describe below has already been described by Diana??

best,
-Rob

>
>
>The main problem of a documentation is that it can be written in different
>ways, which have a varying degree of effectiveness depending on /who/ reads
>them and /when/.
>
>Let me try to explain a bit more.
>
>As an example take any school book.
>
>It can teach the same content by:
>
>1. explaining the theorical architecture and providing corresponding use
>cases
>2. teaching the history of how the theory got made with all the real life
>things that provided the insight needed
>3. answering questions that users might pose as the learning advances
>4. providing clever use-cases that make the student get more insight as the
>explanation advances (learn by doing)
>5. etc...
>
>I've seen this when I wrote a short book on how the computer works, called
>"Computer Architecture".
>It has been useful for many as a reference, and in pa���s a support for
>teaching, but can't be read by itself to learn how to use a Computer.
>
>Every time I read a technical book in my life, I always understand more
>things and in a different way.
>
>What I'm trying to say is that we should find a way of abstracting the
>information in such a way that it can be relaborated and shown to the user
>in many ways, so that we open different communication channels to the same
>knowledge.
>
>What is the smallest unit of information for a Java project?
>What knowledgemap is needed to bind these together?
>What are the communication channels that can be used to render this
>knowledgebase?
>
>Am I starting to see a use for RDF and TopicMaps? ;-)
>
>>They also provide a useful
>>(though not always optimal) way to update the document set. They can
>>also give people a quick overview of a project/software. What else
>>should they address -- in an ideal world?
>>
>>I also think the FAQ dtd needs "last modified" content (as per David's
>>earlier suggestion on cocoon-dev).
>>
>
>+1
>
>--
>Nicola Ken Barozzi                   nicolaken@apache.org
>            - verba volant, scripta manent -
>   (discussions get forgotten, just code remains)
>---------------------------------------------------------------------
>

Re: FAQ [was: Re: documentation architecture?]

[Nicola Ken Barozzi <ni...@apache.org>]

From: "Diana Shannon" <te...@mac.com>

>
> On April 25, 2002, Ken Barozzi wrote:
>
> > From: "Diana Shannon" <te...@mac.com>
> >
> >> IMO, FAQ content should primarily address holes or ambiguity in other
> >> documentation, as well as bugs in code.
> >
> > Not necessarily.
>
> Are you trying to say that FAQs have come to represent the smallest
> granularity of information in a documentation project? If so, I
> certainly agree with you. I'm just arguing for more effective structures
> for new content as well as existing content based on a specific need.

More effective structure +1
Existing content based on a specific need +1
Partially duplicating content because of this -0

If I have to write a paragraph that explains how to install on Weblogic and
then repeat myself partially in the FAQ when I explain that to avoid a
common problem while installing on Weblogic you have to do a specific thing,
I'm not happy.

Having to port the FAQ entry in the docs and keep it only there does not
make me happier.

> I also think we should encourage other types of "granular" content that
> could eventually be aggregated into more comprehensive documents.

+1

>  One
> example is a "Mini-How-To," a document which describes how to accomplish
> a specific task in a consise, action-oriented fashion. The presence of a
> number of similar Mini-How-Tos (variations on a the same topic) may
> reveal the lack of a user comprehension of a design pattern. Thus, a new
> concept document or tutorial might focus on teaching the design pattern,
> using the Mini-How-Tos as examples. Or, let's say you have cookbook
> "recipes" (code snippets with some explanation) submissions. These could
> be migrated into/referred to by a "best practices" guide/tutorial/other
> how-tos.

This comes nearer to my vision, but it's not quite it.

I'm trying to envision a totally different way of describing information.

> > The main problem of a documentation is that it can be written in
> > different
> > ways, which have a varying degree of effectiveness depending on /who/
> > reads
> > them and /when/.
>
> Documents *solve* problems. A poorly written, weakly designed, or
> missing document is a problem.

With "problem ", I mean difficulty for the writers.
To make a book it's difficult to find the right balance between approaches.
But since we're making a (possibly) dynamic documentation system, we don't
necessarily have to choose beforehand.

> > Let me try to explain a bit more.
> >
> > As an example take any school book.
> >
> > It can teach the same content by:
> >
> > 1. explaining the theorical architecture and providing corresponding use
> > cases
> > 2. teaching the history of how the theory got made with all the real
> > life
> > things that provided the insight needed
> > 3. answering questions that users might pose as the learning advances
> > 4. providing clever use-cases that make the student get more insight as
> > the
> > explanation advances (learn by doing)
> > 5. etc...
>
> These are all "methods" used by authors of training/tutorial documents.
> Their degree of effectiveness depends on how and when they are applied.
> Some methods work best with specific types of content/subject matter or
> at a certain point in time (in the learning process).

This is the point for me.
Since our documentation can be used as a "teacher" itself (hey, we can make
a dynamic web application here, let's not forget!), we can think of how to
_guide_ our reader.

I repeat: it's /not/ a book, it's /more/ than a hypertext, it's a dynamic
infoset or whatever you prefer to call it..

> Good writers know
> how to provide the right balance and sequence of theory, analogy, and
> example. They also know how to anticipate common questions as well as
> help users recover from common mistakes. I still think the effectiveness
> of a document -- for its intended audience -- is a concrete result of
> its design, not a function of who/what/where.

"for its intended audience " means who/what/where  ;-)

I take for granted that the same person after a very short time is already
part of a different audience.

> > I've seen this when I wrote a short book on how the computer works,
> > called
> > "Computer Architecture".
> > It has been useful for many as a reference, and in part as a support for
> > teaching, but can't be read by itself to learn how to use a Computer.
>
> A single document isn't supposed to address all possible use cases.
> That's why we have reference guides, tutorials, brochures, newsletters,
> etc. Maybe you're being too critical of yourself as the author ;) ?

Maybe I had too big expectations ;-)

The point is: do we really need to write reference guides, tutorials,
brochures... etc?
Can't we find a way to abstract information into something more granular so
that reference guides, tutorials, brochures, and so on, can be generated
_automatically_ from the same information source?

XML is content. XSL is view. Or only style?

There are high level information explanation systems, like transition trees
and current reality trees.
Can't we use them to represent-collate the information sets?

> > Every time I read a technical book in my life, I always understand more
> > things and in a different way.
>
> Don't you think that's more a reflection of your evolution as a learner?
> I don't think it's a good argument for limiting the classes of documents
> we might develop.

I'm not saying that I want to limit them.

Speaking in other /geeky/ terms, currently "classes of documentation" are
subclasses of a generic document.
The generic document defines paragraphs, strong text parts, lists, etc.
The FAQ class of documents can for example add a structure with sections and
faq-items, that inside use the parent class functionality (lists,
paragraphs, etc).

What I envision instead, is a different thing altogether.
There is *no* class Document, but a Document is solely an
aggregation-digestion of InformationPackets.
These Packets are correlated and described by cognitive and structural maps.
Different Maps represent different views on the same InformationSet
(collection of all the packets).

Documents are just a possible "style" for these views, and an automatic
voice system can be another (like cassette lessons).

> > What I'm trying to say is that we should find a way of abstracting the
> > information in such a way that it can be relaborated and shown to the
> > user
> > in many ways, so that we open different communication channels to the
> > same
> > knowledge.
>
> That's a lofty goal.

I never aim low ;-)

--
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------

Re: FAQ [was: Re: documentation architecture?]

[Diana Shannon <te...@mac.com>]

On April 25, 2002, Ken Barozzi wrote:

> From: "Diana Shannon" <te...@mac.com>
>
>> IMO, FAQ content should primarily address holes or ambiguity in other
>> documentation, as well as bugs in code.
>
> Not necessarily.

Are you trying to say that FAQs have come to represent the smallest 
granularity of information in a documentation project? If so, I 
certainly agree with you. I'm just arguing for more effective structures 
for new content as well as existing content based on a specific need.

I also think we should encourage other types of "granular" content that 
could eventually be aggregated into more comprehensive documents. One 
example is a "Mini-How-To," a document which describes how to accomplish 
a specific task in a consise, action-oriented fashion. The presence of a 
number of similar Mini-How-Tos (variations on a the same topic) may 
reveal the lack of a user comprehension of a design pattern. Thus, a new 
concept document or tutorial might focus on teaching the design pattern, 
using the Mini-How-Tos as examples. Or, let's say you have cookbook 
"recipes" (code snippets with some explanation) submissions. These could 
be migrated into/referred to by a "best practices" guide/tutorial/other 
how-tos.


> The main problem of a documentation is that it can be written in 
> different
> ways, which have a varying degree of effectiveness depending on /who/ 
> reads
> them and /when/.

Documents *solve* problems. A poorly written, weakly designed, or 
missing document is a problem.

> Let me try to explain a bit more.
>
> As an example take any school book.
>
> It can teach the same content by:
>
> 1. explaining the theorical architecture and providing corresponding use
> cases
> 2. teaching the history of how the theory got made with all the real 
> life
> things that provided the insight needed
> 3. answering questions that users might pose as the learning advances
> 4. providing clever use-cases that make the student get more insight as 
> the
> explanation advances (learn by doing)
> 5. etc...

These are all "methods" used by authors of training/tutorial documents. 
Their degree of effectiveness depends on how and when they are applied. 
Some methods work best with specific types of content/subject matter or 
at a certain point in time (in the learning process). Good writers know 
how to provide the right balance and sequence of theory, analogy, and 
example. They also know how to anticipate common questions as well as 
help users recover from common mistakes. I still think the effectiveness 
of a document -- for its intended audience -- is a concrete result of 
its design, not a function of who/what/where.

> I've seen this when I wrote a short book on how the computer works, 
> called
> "Computer Architecture".
> It has been useful for many as a reference, and in part as a support for
> teaching, but can't be read by itself to learn how to use a Computer.

A single document isn't supposed to address all possible use cases. 
That's why we have reference guides, tutorials, brochures, newsletters, 
etc. Maybe you're being too critical of yourself as the author ;) ?

> Every time I read a technical book in my life, I always understand more
> things and in a different way.

Don't you think that's more a reflection of your evolution as a learner? 
I don't think it's a good argument for limiting the classes of documents 
we might develop.

> What I'm trying to say is that we should find a way of abstracting the
> information in such a way that it can be relaborated and shown to the 
> user
> in many ways, so that we open different communication channels to the 
> same
> knowledge.

That's a lofty goal.

Diana

Re: FAQ [was: Re: documentation architecture?]

[Nicola Ken Barozzi <ni...@apache.org>]

From: "Diana Shannon" <te...@mac.com>

> IMO, FAQ content should primarily address holes or ambiguity in other
> documentation, as well as bugs in code.

Not necessarily.

The main problem of a documentation is that it can be written in different
ways, which have a varying degree of effectiveness depending on /who/ reads
them and /when/.

Let me try to explain a bit more.

As an example take any school book.

It can teach the same content by:

1. explaining the theorical architecture and providing corresponding use
cases
2. teaching the history of how the theory got made with all the real life
things that provided the insight needed
3. answering questions that users might pose as the learning advances
4. providing clever use-cases that make the student get more insight as the
explanation advances (learn by doing)
5. etc...

I've seen this when I wrote a short book on how the computer works, called
"Computer Architecture".
It has been useful for many as a reference, and in part as a support for
teaching, but can't be read by itself to learn how to use a Computer.

Every time I read a technical book in my life, I always understand more
things and in a different way.

What I'm trying to say is that we should find a way of abstracting the
information in such a way that it can be relaborated and shown to the user
in many ways, so that we open different communication channels to the same
knowledge.

What is the smallest unit of information for a Java project?
What knowledgemap is needed to bind these together?
What are the communication channels that can be used to render this
knowledgebase?

Am I starting to see a use for RDF and TopicMaps? ;-)

> They also provide a useful
> (though not always optimal) way to update the document set. They can
> also give people a quick overview of a project/software. What else
> should they address -- in an ideal world?
>
> I also think the FAQ dtd needs "last modified" content (as per David's
> earlier suggestion on cocoon-dev).

+1

--
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------

FAQ [was: Re: documentation architecture?]

[Diana Shannon <te...@mac.com>]

Nicola Ken Barozzi wrote:

> No AFAIK. The Faq DTD is a crucial poin that needs further discussion 
> and
> addressing, since it's basically the result of community know-how, the 
> real
> core of the project.

Many open source projects vary greatly in how they define what's 
appropriate content for an FAQ . For example, one project's "FAQs page" 
serves as another project's "Manual". That's ok, but is it ideal? The 
number and scope of FAQs are revealing indicators for the maturity level 
of a project's documentation effort. However, over time, I think FAQ 
content should migrate to more appropriate document types: how-tos, 
guides, tutorials. Nevertheless, 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". Such 
users should *still* have a channel through which to contribute -- 
assuming the topic they want to address is valid. I believe technical 
and editorial review can provide sufficient quality assurance.

I'm certainly not suggesting we impose restrictions on the scope of FAQ 
content for Apache projects. Instead we can provide other document 
guidelines/resources to help better these projects better manage and 
direct community contributions. (I will be working on this for Cocoon.) 
IMO, FAQ content should primarily address holes or ambiguity in other 
documentation, as well as bugs in code. They also provide a useful 
(though not always optimal) way to update the document set. They can 
also give people a quick overview of a project/software. What else 
should they address -- in an ideal world?

I also think the FAQ dtd needs "last modified" content (as per David's 
earlier suggestion on cocoon-dev).

Diana

Re: documentation architecture?

[Nicola Ken Barozzi <ni...@apache.org>]

From: "Diana Shannon" <te...@mac.com>

> Is it within the scope of Forrest to offer projects suggested
> mechanisms/approaches/templates/schema for documentation? For example,

IMO yes.

> let's say a project had the following documentation offerings.
>
> documentation categories
> - FAQs
> - mini how-tos
> - guides (e.g., component-oriented)
> - tutorials
> - examples/cookbook "recipes"
> - case studies
> - reference guides
> - quick-reference guides
>
> For example, you may want to have:
> - "What's New" page within each documentation category
> - "Features" page (any document category)
> - Ability to search/browse within each documentation category as well as
> across all documentation categories, based on content, last modified
> date (thanks David Crossley).
> - Dataset scalability mechanism (e.g., when number of how-tos files
> grows too large)
> - Contributor's info (instructions/info, author/edit guidelines,
> how-tos, schema)

Please look at http://jakarta.apache.org/poi/ .

There is a menu on the left organized using the CDC principle:
Community-Docs-Code.

What does it mean?

A project at Apache seems to resolve around these three points.
The main thing is the community, without which nothing gets done.
Then the Documentation, which is the step to start understanding the
Community.
Finally the code, which is what the docs represent.

This ladder is usually climbed from the bottom: first you look at the code,
start reading the docs, and finally approach the community.

the scheme is somewhat like the one I include as an attachment.

I propose that we start from this basis and enhance it.

> Also, does Forrest's FAQ dtd (with all FAQ elements in a single file)
> properly anticipate processing/administering large numbers of FAQs,
> particularly when you factor in potential community contributions?

No AFAIK. The Faq DTD is a crucial poin that needs further discussion and
addressing, since it's basically the result of community know-how, the real
core of the project.

> Is it within the mission of Forrest to implement/provide these items?

Yes.

Now that I think of it, in the goals of Forrest there is a build system.

But now for the build there is Centipede, and I would remove that from the
goals.

This is what I envision:

Forrest: site (community+docs)
Alexandria: project code comprehension (docs+code)
Gump: module builds for quality assesment and CI(community+code)
Centipede: Build system to interact with all three.

Currently Centipede has a Gump descriptor and uses a modified version of
Forrest for the docs (committing today-tomorrow I still hope).
It also uses code documentation that I would like to see in Alexandria; I
didn't write it myself, and will ask maybe to donate it there.

What do you think?

--
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------

Re: documentation architecture?

[Nicola Ken Barozzi <ni...@apache.org>]

oops, the attachment ;-)

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------