Mailinglist Archive: opensuse-doc (14 mails)

< Previous Next >
Re: [opensuse-doc] The openSUSE distribution chages are way ahead of documentation?
  • From: Rajko M <rmatov101@xxxxxxxxxxx>
  • Date: Sat, 30 Sep 2006 11:15:10 -0500
  • Message-id: <451E980E.1020100@xxxxxxxxxxx>
Sean Wheller wrote:
> 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.

The Docbook is marked as default format, but I've never seen any editor
mentioned that will help document writers to concentrate on writing, not
on learning of document source format, and all other stuff like
conversion methods to different formats, that has little to do with
actual writing.

> 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.

Editor? Like mentioned above.

> 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?

I hope they will. Though except small intro I wasn't able to find (guess
what) documentation:

In the meantime we can think about what else we would need.
- The templates and forms as a help for occasional contributors is what
we are missing right now.
- The tools (ways) to announce that we plan work on some documents, the
searchable database of already active projects, and their status.
This will give us ability to see active, stale and unmaintained
projects. Projects that need help. The idea is pretty much the same as, but with focus on SUSE related aspects.
- The categorization, naming structure.
I started that, jdd started that, and everything didn't moved from the
beginning. If you ask me for the links, I lost even that. It is on the
openSUSE wiki :-) (this sounds as helpful, as many help files)

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

< Previous Next >
List Navigation
Follow Ups