[generguide-devel] Requirements: Documentation Format

[Sean W. <se...@ya...>]

I am new to the project. So I hope you will be able to
clarify some of the concerns I will raise in this
message.

I would like to start by addressing The Requirements.
As this subject is large I will limit myself to the
Documentation Format.

I hope that your responses will identify some
potential areas where I may start working without the
risk of changing the definition or focus of the
project.

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.
 
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.
 
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.

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.

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.
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?
2. Again I think that rdocformat3.1 and rdocformat3.2
are not required.

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.

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. 
2. This is also not a requirement that fits under the
category of Documentation Format.

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.

Sean Wheller
se...@ya...

 


__________________________________
Do you Yahoo!?
Yahoo! SiteBuilder - Free, easy-to-use web site design software
http://sitebuilder.yahoo.com