On Wednesday 16 November 2011 10:00:22 pm Darrell Anderson wrote:
> 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?

I agree with the point of avoiding markup. There is a markup format that most
people will be familiar with from Wikipedia, but a switch to MediaWiki seems
unlikely, and not everybody will be comfortable with that.

I think most hard-core F\OSS users will want to avoid proprietary softwares,
and not everybody can afford programs like MS Office. Yes, LibreOffice does
have support for doc and docx formats, but I doubt it supports all features,
that is not a garentee, and the only place I'd use the MS format is for my
job anyway. Personally, I believe that since we're a F\OSS community, we
should use F\OSS software and formats. I'd say it's acceptable to distribute
PDFs of the finished guides, but I certainly think we should avoid them until
then.

We're probably better off using either LibreOffice or KOffice. I don't think
anybody will harp on us for using LibreOffice because of how widely-used it
is, and how widely-used it's predecessor was. It's also open source, and it
uses the same ODT format as KOffice. In fact, most open source editors
support ODT, and I remember opening an ODT at school using MS Office 2007,
before realizing that I forgot to convert it to their format, so anybody who
does use MS Office should be able to contribute.

Another option is using an HTML IDE. Most open source ones produce plain HTML
code without all the excessive meta tags. Some add a meta tag to identify the
IDE, but otherwise just the code needed to properly display the page.

If we put the guides in their own section of git (I think that was mentioned
earlier in this thread) and make that section read-only, that'll make it
easier to keep track of the changes, collaborate, and revert in case of a
mistake.

Kristopher Gamrat
Ark Linux webmaster
http://www.arklinux.org/