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: http://forge.joomla.org/sf/docman/do/listDocuments/projects.docbook_collab/d... 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 sourceforge.net, 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) -- Regards, Rajko. Visit http://en.opensuse.org --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org