Re: [generguide-devel] Requirements: Documentation Format

[Cameron S. <ca...@sh...>]

FYI Artur, Sean is now subscribed to generguide-devel using his yahoo email 
address.  Hopefully we can move forward with our discussions now.

On Monday 08 Sep 2003 12:47 am, Sean Wheller wrote:

> rdocformat1 > Documentation shall be stored in
> standards based format.
>
> The format specified is limited to Simplified Docbook.
>
> 1. I am not sure that Simplified Docbook can be
> referred to as a format. Rather it is a Document Type.

ok.

>
> 2. Simplified Docbook is a Subset of the DocBook XML
> Document Type. It is designed to accommodate documents
> such as articles, white papers, release notes etc.
> This means that generguide is inappropriately
> specifying the use of a Document Type. The generguide
> framework enables the development of books.

ok.

>
> 3. Simplified Docbook is only one of the standards
> based Document Types available. Perhaps the high-level
> principles of the generguide framework should be more
> generic to ensure wider application.


OK.  I accept all these suggestions.  The reason for specifying a 
Documentation Type is so that we can select appropriate tools.  Currently we 
provide Norman Walsh's docbook stylesheets which are used for Docbook XML and 
Simple Docbook XML.  So I'm happy to expand the scope to include Docbook XML.

If we add more document types than this, we need to consider how our tools can 
process them.

Specific guides may want to limit the document type used on their project to 
Simple docbook.  (Eg for a Developer's guide Full docbook is not required and 
hence using simple docbook makes it easier for new tech writers).

So our configuration file should have a field which specifies what document 
type to use.

>
> rdocformat2 > Documentation should be stored in a
> format which can be transformed into other common
> formats. In particular: text, html, pdf.
>
> 1. The format is XML, conforming to standards based
> Document Types, like Simplified Docbook or Docbook
> XML, as specified by the project.

Ok, but there needs to be a Stylesheets written for the XML before it can work 
within the generguide framework.

>
> rdocformat3.1 > Documentation shall be editable with
> an easy to use, no cost, WYSIWYM editor.
>
> 1. If rdocformat2 is specified as per the description
> I have provided, then the need for rdocformat3.1 is
> obviated to the extent that an author can use any
> editor of their choice.

Yes, that is true, however I still think this is an end user requirement.
In the requirements I try to list all a user's needs, independant of the 
technical solution we provide.
If at a later stage we decide our approach is not working, and we need to 
change our design, then we need to make sure this requirement is met.

Unfortunately most tech writers I've met don't like writing documentation in 
emacs or vi, which is probably why there are so many WORD documents around.

> 2. What is important is that the content conforms to
> the Document Type specified by the project and that it
> is Valid and Well-formed XML.
>
> rdocformat3.2 > Documentation shall be editable with
> an easy to use, open source, WYSIWYM editor.
>
> 1. Is there a reason why this rec is the same as
> rdocformat3.1?

It is not quite the same.  One refers to a free (as in free beer), the other 
refers to open source.
For many open source developers, this is an important difference and for this 
reason, XXE which is a great free docbook editor is not mentioned in the 
Linux Documentation Project HOWTOs.

> 2. Again I think that rdocformat3.1 and rdocformat3.2
> are not required.

If it is ok with you, I'd prefer to keep them.

>
> rdocformat4 > The learning curve required to write
> documentation should be kept as short as possible in
> order to attract authors.
>
> 1. This is not a requirement that fits under the
> category of Documentation Format.

Fair enough, we can move it under a different heading.

>
> rdocformat5 > The documentation format shall allow
> sections of a Generic Guide to be edited and stored
> separately to the Project Guide.
>
> 1. The format is XML. Better refer to architecture or
> structure.

ok.

> 2. This is also not a requirement that fits under the
> category of Documentation Format.

Sure, put it somewhere else.

>
> That is it for today. As I said, I will limit myself
> to the Documentation Format. In due course I will take
> a the same approach with the remainder of the
> requirements.

This is a good start.  I look forward to the next installments.
I suggest you use the latest version of this document from CVS instead of from 
the web page.  The website is not the latest version.
You can find it in:
generguide/docs/sdocbook/generguide.xml

Would you like to become editor of the requirements documentation?
I suggest that you propose changes to the requirements on the email list here 
(as you have done).  Anything that we agree to you can then update in the 
requirements section.



-- 
Cameron Shorter              http://cameron.shorter.net
Open Source Developer        http://generguide.sourceforge.net
                             http://mapbuilder.sourceforge.net
                             http://geotools.org
Senior Software Engineer     http://www.adi-limited.com