forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <terrac...@mac.com>
Subject FAQ [was: Re: documentation architecture?]
Date Thu, 25 Apr 2002 13:30:12 GMT
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


Mime
View raw message