On 11/02/16 01:53, Leslie S Satenstein wrote:
I favour a wiki approach to documentation. I also favour using
libreOffice with the "Produce Docbook" output format.
I *like* gvim, it's how I write XML, but gvim and LibreOffice are huge
barriers to entry for people who just want to correct a typo or add a
hint about how to do something.
I wrote "This is a test of docbook output" with LibreOffice
and saved the output in docbook format.
This is the resulting output<?xml version="1.0"
encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<article lang="">
<para>This is a test of docbook output</para>
<para/>
</article>
Writing with WYSIWYG (What you see is what you get), is great for technical writing. As
well, the markup and collaboration tools in LibreOffice are what appeals to many
individuals.Translation from English to other languages is made easier by using web
services from Google, Microsoft and others.
I would also suggest you compare these two links.Fedora
https://docs.fedoraproject.org/en-US/index.html
SUSEhttps://en.opensuse.org/Main_Page
Which of the two is more inviting and easier to use?
This is orthogonal, making the docs site look like a wiki is just
tweaking the site html and CSS, but it wouldn't address the usability of
creating and editing content.
Here is how you could make the docs site look if that is what we where
discussing.
https://jfearn.fedorapeople.org/fdocs/en-US/index.html
Really you should compare some actual docs pages like
https://www.suse.com/releasenotes/x86_64/openSUSE/12.3/
https://jfearn.fedorapeople.org/fdocs/en-US/Fedora/20/html/Release_Notes/...
https://docs.fedoraproject.org/en-US/Fedora/23/html/Release_Notes/index.html
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux
Someone at Suse should package publican, I'll do a brand for them for a
cider.
Cheers, Jeff.
--
Jeff Fearn
Senior Software Engineer
PnT - DevOps - Development
Red Hat Asia Pacific Pty Ltd
http://dilbert.com/fast/2004-08-17/