Mailinglist Archive: opensuse-doc (14 mails)

< Previous Next >
Re: [opensuse-doc] The openSUSE distribution chages are way ahead of documentation?
  • From: Sean Wheller <sean@xxxxxxxxxxxxx>
  • Date: Sat, 30 Sep 2006 11:38:47 +0200
  • Message-id: <200609301138.47625.sean@xxxxxxxxxxxxx>
On Saturday 30 September 2006 11:03, Alexey Eremenko wrote:
> I believe that in order to solve documentation problem, community must
> help.
> In order for the community to help, we need tools - that is wiki (which
> exists on the webpage) *and* a conversion tool to convert that wiki to RPM
> to install offline. There is *no* such conversion tool available, and so it
> makes me much less interested to contribute to wikis, because they are not
> installed in the final distro.
> I agree to contribute more articles to our openSUSE wiki *only* if Novell
> agrees to distribute this as RPM on the standard openSUSE DVD ISO.
> Until today I have contributed few items: such as "FreeNX" server & "Qemu"
> configuration articles to wiki, but those are not included in the final
> distro, which makes me very unhappy about continuing contribution...
> To Novell: please allow the community to write docs, that will be included
> in the distro  for offline use (in RPM package, HTML format).

I agree with the sentiments of your message.

However, I am not a lover of wiki. Wiki is a content Motel. everything
check-in, but nothing ever checks out. Porting wiki to more useful formats
such as Docbook XML or DITA is a RPITA and adds an additional step in the
process of packaging.

However, I do agree that a web-based solution does reduce the barrier to entry
for just anyone who wants to contribute something in the way of docs. One
idea I have been playing with is th evision of editing Docbook under a
web-based editor. So giving wiki-like docbook editing capabilities.

This could help eliminate the problem of preprocessing wiki stuff to Docbook.
If the source remains as docbook it would also make integration with the
current toolchain used by the doc team much easier. It would also enable
people that donot want to use a wiki-like enviroment, to edit the docbook src
as a working copy of SVN. In short the level of indirection between editing
environments would be greatly improved.

There is a project that is a Joomla component, called docbook::collab. This
demonstrates the direction I am thinking in. However, docbook::collab
currently has some retrictions.
1. It uses BitFlex Editor. This supports creation of sdocbook. OK you can
import full-docbook, but only edit using sdocbook.
2. It stores documents in MySQL. Not he best place to have these resources if
you want SVN and piping into the build and translation processes.

Perhaps people could look at this type of solution?

Ask me about the Monkey.

Sean Wheller
Technical Author
To unsubscribe, e-mail: opensuse-doc+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-doc+help@xxxxxxxxxxxx

< Previous Next >
List Navigation
Follow Ups