> >> I would definitely encourage the usage of an open
> format flat file (or
> >> files), such as fodt or some sort of Latex format,
> in the GIT
> >> repository.
> >> This would greatly simplify differences between
> versions (if needed),
> >> and
> >> thereby make it easier for those without write
> access to GIT to jump in,
> >> edit the document, and submit a patch with their
> additions.
> >
> > Not everybody will have a Latex editor at the ready. I
> don't know what
> > fodt
> > is. Most people will have an ODT-compatible editor
> such as LibreOffice or
> > AbiWord (I think even MS Office can read/save ODT
> files since their 2007
> > edition).
> 
> fodt is the Flat ODT format, which OpenOffice/LibreOffice
> can read and
> write natively.  The advantage over ODT is that it is
> not a binary blob,
> so it doesn't take up massive amounts of space in our SCM,
> and patches can
> be made/applied (this is important in a collaborative
> environment outside
> of something like Etherpad).

There are several responses to my original query about a user guide. I'll use this most recent reply to respond.

Side comment: I want to produce something for R14. Something.

There are two aspects to this discussion. The second part can be split into two components.

One aspect is the formats we want to produce. The other is the tools we use. Within this latter area we have the desire to produce professional user guides. We also need to maintain TDE Help files, much of which are long overdue for reviews and updating.

A) Formats:

HTML and PDF. These formats are portable and do not require being connected to the web. The HTML version may be duplicated at the web site and is easy to slip into a distro's desktop. PDF is useful for studying without flip-flopping around computer screens because they are designed for printing.

B) Tool chains:

1) User guides? How do other groups support both formats? Docbook is somewhat popular but a custom post processing tool chain is needed to produce quality professional output. This post processing tool chain is not easy to create or use. Additional challenge: few people like editing in a raw markup language, which discourages people from helping.

2) Help files: they are in Docbook. I don't believe we need to perform any post processing on these files. I believe the underlying viewing engine does that on-the-fly. These files can be edited and merged upstream like software patches. Yet we still need to edit in raw markup. Is there a better way?

More to consider:

Do we want to showcase Trinity and use only tools provided by Trinity to maintain the user guides and Help files? What is the perception by others if we uses tools not in Trinity?

Tools like Latex are useful to a minority of people, but tools like that will not be adopted by the typical person who wants to help with documentation. What tools do we use to encourage others to help and participate? Do we need a two step process (writer to editor) with respect to other people participating?

With the user guides we want to modularize information --- something commonly called master documents. In the proprietary world MS Word and Adobe FrameMaker support this concept. I think LibreOffice Writer does (but Writer is not a Trinity app). I don't know whether KWord supports the feature although KWord supports ODT.

Traditionally word processors support PDF exporting quite well but produce horrible non-validating HTML. Has this changed?

Darrell