You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Ross Gardler <rg...@apache.org> on 2006/03/01 15:01:39 UTC
[Docs] FAQ Document Type
A couple of weeks ago I promised to set up a FAQ system in Daisy. I've
now done this.
Creating a FAQ
==============
There is a "FAQ" document Type. This is a simple document in which the
document title should be the question and the content should be the answer.
To illustrate things I have copied the "installation faqs" from
http://cocoon.apache.org/2.1/faq/faq-install.html into individual FAQ
documents, for example:
http://cocoon.zones.apache.org/daisy/documentation/799.html?branch=1&language=1
http://cocoon.zones.apache.org/daisy/documentation/806.html?branch=1&language=1
Tagging Faqs
============
There is an (optional) "tags" field. This can take any number of "tags"
for categorisation of the content. These tags can then be used by the
Daisy query language to build dynamic FAQs.
To create the Installation FAQ index we use a query such as:
select name
where documentType='FAQ'
and InCollection('documentation')
and $Tags='Installation'
Which results in the page at
http://cocoon.zones.apache.org/daisy/documentation/faq.html
FAQ Reuse
---------
Custom FAQs can be built from multiple FAQ documents by adding relevant
tags to the appropriate FAQ entries and building a query such as that
above. That is, a single FAQ may appear in more than one FAQ index.
For example, we may have a number of CForm FAQs some of which deal with
the XYZ widget, while others deal with different aspects of CForms.
Tagging FAQs effectively, say with "CForm" and "XYZ widget", allows us
to create a CForm FAQ index which includes all relevant FAQs. At the
same time we can use a search on the "XYZ widget" tag to include the
relevant FAQs within the documentation for that individual widget.
FAQ Navigation
==============
It is also possible to create dynamic FAQ indexes in the navigation
menu, for example, see the FAQs/Installation node (expanded on
http://cocoon.zones.apache.org/daisy/documentation/faqs/install/799.html )
----
So, if people like this, we should migrate all FAQs from the legacy docs
into this format, as well as including relevant ones from the Wiki.
Ross
Re: [Docs] FAQ Document Type
Posted by Bruno Dumon <br...@outerthought.org>.
On Sat, 2006-03-04 at 19:04 +0000, Ross Gardler wrote:
> Bruno Dumon wrote:
> > On Wed, 2006-03-01 at 14:01 +0000, Ross Gardler wrote:
> >
> >>A couple of weeks ago I promised to set up a FAQ system in Daisy. I've
> >>now done this.
> >>
> >>Creating a FAQ
> >>==============
> >>
> >>There is a "FAQ" document Type. This is a simple document in which the
> >>document title should be the question and the content should be the answer.
> >>
> >>To illustrate things I have copied the "installation faqs" from
> >>http://cocoon.apache.org/2.1/faq/faq-install.html into individual FAQ
> >>documents, for example:
> >>
> >>http://cocoon.zones.apache.org/daisy/documentation/799.html?branch=1&language=1
> >>http://cocoon.zones.apache.org/daisy/documentation/806.html?branch=1&language=1
> >>
> >
> > <snip the details/>
> >
> >>----
> >>
> >>So, if people like this, we should migrate all FAQs from the legacy docs
> >>into this format, as well as including relevant ones from the Wiki.
> >>
> >>Ross
> >
> >
> > Thanks for setting this up. I have some reservations though about
> > copying the FAQs from the legacy docs. I haven't read them all but a lot
> > of them have become either incorrect or irrelevant. One of the reasons
> > for the "new documentation" is that we can leave behind the outdated
> > information.
>
> Yes, that makes sense, I'm a little behind with Cocoon, so do not have
> the knowledge to decide what goes in and what stays out.
>
> > I'd also like to change the
> > query in the navigation to a query in a document: having the long
> > questions in the navigation doesn't make sense I think.
>
> +1
>
> I only really threw these in as examples. Later I realised I had not
> done an example of creating a complete FAQ document (i.e. with questions
> & answers) only of indexes (bth navigation and in document).
>
> None daisy users should be aware that the query system in Daisy is
> superb and very flexible. If folk want something better than is
> currently in place then just ask how (or do it).
>
I now made this of it:
http://cocoon.zones.apache.org/daisy/documentation/856.html
I've added a forms-related FAQ and a flowscript-related FAQ.
> > Similar to the FAQ doctype, I'd also like to set up a "GlosarryItem"
> > doctype which can be used to provide short explanations of
> > Cocoon-specific terms (such as sitemap, subsitemap, FOM, flowscript,
> > blocks, real blocks, ...).
>
> +1
And the glossary is here:
http://cocoon.zones.apache.org/daisy/documentation/857.html
--
Bruno Dumon http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
bruno@outerthought.org bruno@apache.org
Re: [Docs] FAQ Document Type
Posted by Ross Gardler <rg...@apache.org>.
Bruno Dumon wrote:
> On Wed, 2006-03-01 at 14:01 +0000, Ross Gardler wrote:
>
>>A couple of weeks ago I promised to set up a FAQ system in Daisy. I've
>>now done this.
>>
>>Creating a FAQ
>>==============
>>
>>There is a "FAQ" document Type. This is a simple document in which the
>>document title should be the question and the content should be the answer.
>>
>>To illustrate things I have copied the "installation faqs" from
>>http://cocoon.apache.org/2.1/faq/faq-install.html into individual FAQ
>>documents, for example:
>>
>>http://cocoon.zones.apache.org/daisy/documentation/799.html?branch=1&language=1
>>http://cocoon.zones.apache.org/daisy/documentation/806.html?branch=1&language=1
>>
>
> <snip the details/>
>
>>----
>>
>>So, if people like this, we should migrate all FAQs from the legacy docs
>>into this format, as well as including relevant ones from the Wiki.
>>
>>Ross
>
>
> Thanks for setting this up. I have some reservations though about
> copying the FAQs from the legacy docs. I haven't read them all but a lot
> of them have become either incorrect or irrelevant. One of the reasons
> for the "new documentation" is that we can leave behind the outdated
> information.
Yes, that makes sense, I'm a little behind with Cocoon, so do not have
the knowledge to decide what goes in and what stays out.
> I'd also like to change the
> query in the navigation to a query in a document: having the long
> questions in the navigation doesn't make sense I think.
+1
I only really threw these in as examples. Later I realised I had not
done an example of creating a complete FAQ document (i.e. with questions
& answers) only of indexes (bth navigation and in document).
None daisy users should be aware that the query system in Daisy is
superb and very flexible. If folk want something better than is
currently in place then just ask how (or do it).
> Similar to the FAQ doctype, I'd also like to set up a "GlosarryItem"
> doctype which can be used to provide short explanations of
> Cocoon-specific terms (such as sitemap, subsitemap, FOM, flowscript,
> blocks, real blocks, ...).
+1
Ross
Re: [Docs] FAQ Document Type
Posted by Bruno Dumon <br...@outerthought.org>.
On Wed, 2006-03-01 at 14:01 +0000, Ross Gardler wrote:
> A couple of weeks ago I promised to set up a FAQ system in Daisy. I've
> now done this.
>
> Creating a FAQ
> ==============
>
> There is a "FAQ" document Type. This is a simple document in which the
> document title should be the question and the content should be the answer.
>
> To illustrate things I have copied the "installation faqs" from
> http://cocoon.apache.org/2.1/faq/faq-install.html into individual FAQ
> documents, for example:
>
> http://cocoon.zones.apache.org/daisy/documentation/799.html?branch=1&language=1
> http://cocoon.zones.apache.org/daisy/documentation/806.html?branch=1&language=1
>
<snip the details/>
>
> ----
>
> So, if people like this, we should migrate all FAQs from the legacy docs
> into this format, as well as including relevant ones from the Wiki.
>
> Ross
Thanks for setting this up. I have some reservations though about
copying the FAQs from the legacy docs. I haven't read them all but a lot
of them have become either incorrect or irrelevant. One of the reasons
for the "new documentation" is that we can leave behind the outdated
information.
I'll have a look at removing those I think shouldn't be included
anymore, and maybe adding some fresh ones. I'd also like to change the
query in the navigation to a query in a document: having the long
questions in the navigation doesn't make sense I think.
Similar to the FAQ doctype, I'd also like to set up a "GlosarryItem"
doctype which can be used to provide short explanations of
Cocoon-specific terms (such as sitemap, subsitemap, FOM, flowscript,
blocks, real blocks, ...).
--
Bruno Dumon http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
bruno@outerthought.org bruno@apache.org