Message: previous - next
Month: November 2011

Re: [trinity-devel] Trinity User's Guide

From: "Timothy Pearson" <kb9vqf@...>
Date: Wed, 16 Nov 2011 22:19:31 -0600
> On 16 November 2011 22:46, Kristopher John Gamrat
> <chaotickjg@...>wrote:
>> 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
>> 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
> 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:
> 1) Any editor works
> 2) Formatting can be learned in less than 10 minutes, similar to wikipedia
> 3) We can use Git to track changes in the repository
> 4) 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.