NOV
2
2000

KDE Documentation needs your help!

The KDE Team needs your help with writing documentation for all of the great applications in KDE! This is your opportunity to help KDE become useful to the users of KDE applications at any level. You don't need to be a professional writer, and you don't even need to know everything about a program. For more information, please visit us at the Editorial Team website, or contact Mike McBride if you are interested.

Comments

Agreed. Documentation does need work :)

Dave

P.S.: Konqueror rocks! :)


By David B. Harris at Thu, 2000/11/02 - 6:00am

I've wanted to volunteer in this arena for quite some time. The only thing holding me back is I haven't found too many resources for documentation writers. I've started writing some documentation using RoboHelp HTML (yes, I know it's a windows program but it's also the best as far as I'm concerned when it comes to HTML documentation). Only thing is, I figured it wouldn't be accepted by the KDE community so I scrapped it.

Frankly, I don't know SGML and really don't have a desire to learn and kwrite is too ... well ... let's just say for DTP I think it's great, for Word Processing I think it's too cumbersome. So, my tools are StarOffice, kedit, or vi.

Any suggestions?


By George Ellenburg at Thu, 2000/11/02 - 6:00am

An emacs-based package for writing SGML can be found at http://www.oasis-open.org/cover/tei-PSGML-SK.html, and probably elsewhere. It works on Windows; I have used it with some success.


By Winter Laite at Thu, 2000/11/02 - 6:00am

You should not let SGML knowledge (or lack there of) stop you from helping. Many of KDE's documentation authors write their documentation in ASCII text.

One of our reviewers, who knows a lot about docbook, and KDE documentation can convert that documentation to docbook very easily.

So please reconsider. We are happy to recieve good quality documentation (either docbook or text). The content is the hard part. We will help you with the docbook (or just do it for you if you don't want to learn it).


By Mike McBride at Fri, 2000/11/03 - 6:00am

Why not have an on-line (that is pulled off-line for initial distribution) set of docs that can be annontated...

I'm picturing something like the FAQs on SourceForge, but with editorial control over what becomes cannon, with the unedited user comments at the bottom of the documentation a la PHP or MySQL's site.

That way, the documentation becomes a living document of the community that uses it.

--
Evan


By Evan "JabberWok... at Thu, 2000/11/02 - 6:00am

> That way, the documentation becomes a living
> document of the community that uses it.

Although it may be a good idea, you must remember that not all the people in the world speak English. The KDE documentation is (being) translated into many other languages, which I fear wouldn't be possible the way you suggested...

Regards,
Lukas Tinkl
Czech KDE team


By Lukas Tinkl at Thu, 2000/11/02 - 6:00am

which I fear wouldn't be possible the way you suggested...

Actually, having the ability for a normal user to be able to contribute translations while using the program would (in my eyes) make it far *easier* to translate the help.

Somebody using an obscure dialect of a regional language might not be available to formally join the KDE effort, but if it's simply a matter of clicking a "Help Translate" button and typing a translation actually *in* the help window, and thus posting it to the global help documentation, I would imagine that everybody would add their own effort.

Again, some sort of editorial control would be in place for review purposes, but I would imagine that opening the help up to the maximum extent possible would be a Good Thing.

--
Evan


By Evan "JabberWok... at Thu, 2000/11/02 - 6:00am