On 16 November 2011 22:46, Kristopher John Gamrat chaotickjg@gmail.comwrote:
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:
- 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.
- 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/
If you read up on markdown like I posted earlier you would realize markdown is almost identical to the Mediawiki style (format is almost the same, but it has the same ideas). Honestly Libreoffice is going to give us a binary blob as well as KOffice.
Markdown is just as easy as learning how to use libreoffice. The major advantages with markdown are:
- Any editor works
- Formatting can be learned in less than 10 minutes, similar to wikipedia
- We can use Git to track changes in the repository
- It is easy to convert into XML, PDF, whatever you like to publish. This
makes it very versatile when considering options for distribution. 5) Readability, No nasty tags or hacks like HTML requires. No programming or web development knowledge.
Can you provide a similar list for LibreOffice? I'd like to pick the best option before we get to far in
Calvin Morrison
LibreOffice can do all of the above, and more, as most of the computer literate world knows how to use a word processor.
We want to make it *easy* for people to contribute to the documentation. Any new language learning requirements, no matter how "simple", *will* cause people not to contribute.
Tim