Version: 0.11.20 (using KDE 3.3.2, (3.1)) Compiler: gcc version 3.3.5 (Debian 1:3.3.5-6) OS: Linux (i686) release 2.6.8-1-386 I have had trouble performing simple tasks in K3B because of the lack of good documentation in, or linked to from, the application. I find much more useful information on the web than is available inside the application. For example. How to burn an ISO image is not documented in the built in documentation. How to create a bootable CD from scratch is also not in the documentation. I would be happy to contribute time and effort to documentation. An online wiki format would be ideal and a snapshot could be made of the wiki and included with the application for offline help.
And I would be happy to have someone working on a good handbook. :)
If you got some documentation, I'll mark it up for you so that it can be included in the official docs. The KDE Documentation team also does this kind of work. I'd definitely like a wiki too, the question is who will do it. Having hit the right bug report: Is it possible to also update doc changes in minor releases? After all, it has been a relatively long time since I sent in the new Menu Commands page, and it's still just in CVS. This is quite at the end of the 0.11 series. Imagine someone committing documentation for K3b 0.12 and waiting for it for I don't know how long...
Theoretically yes. Practically: I am only one person (except for Chris working on the vcd project). So I try to keep stuff besides coding at a minimum (don't know if this is correct english, I am really tired ;) Regarding the docu: there is none. I never wrote any except for the new dcop interface docu in cvs.
myself: >If you got some documentation, I'll mark it up for you so that it can be included in the official docs. Sebastian Trueg: > Regarding the docu: there is none. I never wrote any except for the new dcop interface docu in cvs. Sorry for being unclear, of course I meant kevin to maybe send me some stuff. I know you're more a coder than a doc writer. Although, and that also must be said in defense of K3b's documentation: The What's This items are great. They are virtually everywhere, and they explain most of the functionality. If the user knows how they can be accessed ;-)
Then this will work out well since my coding kung fu skills lack sufficient power. I would be happy to put some time into documenting K3b. I'm new to the development end of Linux so I don't know if there is a place to put documentation or a specific format that needs to be used. I like the idea of a wiki which would move the burden of documentation to whoever wants to do it rather than channeling it through K3b development team. I'll do some looking around today for an existing wiki to put documentation on. preferably hosted by KDE but who knows where I'll end up. Can you send me templates or something that I can use for formatting. Can you also send me some of the FAQ that you receive which I'll use as a starting point for my documentation. Thanks, Kevin Jakob Petsovits wrote: >------- You are receiving this mail because: ------- >You reported the bug, or are watching the reporter. > >http://bugs.kde.org/show_bug.cgi?id=100839 > > > > >------- Additional Comments From jpetso gmx at 2005-03-07 00:29 ------- >myself: > > >>If you got some documentation, I'll mark it up for you so that it can be included in the official docs. >> >> > >Sebastian Trueg: > > >>Regarding the docu: there is none. I never wrote any except for the new dcop interface docu in cvs. >> >> > >Sorry for being unclear, of course I meant kevin to maybe send me some stuff. I know you're more a coder than a doc writer. Although, and that also must be said in defense of K3b's documentation: The What's This items are great. They are virtually everywhere, and they explain most of the functionality. If the user knows how they can be accessed ;-) > > >
> I'm new to the development end of Linux so I don't know if there is a place to put documentation or a specific format that needs to be used. Currently, the place to put documentation is the attachment of an email to one of the people taking care of this. KDE's documentation (so also K3b's) is written in docbook format, which is an XML file with certain tags that should be used. Like [url]www.somelocation.com[/url] in wiki markup language it describes the text by encapsulating it in <tags/>. If you want to learn docbook, just look at the documentation sources in /usr/share/doc/HTML/ or dive into the KDE DocBook Authors guide at http://i18n.kde.org/doc/markup/index.html. > I like the idea of a wiki which would move the burden of documentation to whoever wants to do it rather than channeling it through K3b development team. This is a wrong assumption, because wiki documentation would also be channeled through the development teams (until it's automated, which won't happen for quite some time in KDE). The only advantage would probably be more people submitting documentation because it's easier for them. > I'll do some looking around today for an existing wiki to put documentation on. preferably hosted by KDE but who knows where I'll end up. You can put anything you want at wiki.kde.org which is the only KDE hosted wiki. But I'd find it easier if you just send me plaintext files (or docbook, whatever you like) of additions and changes to the documentation. I then would mark them up as docbook and forward them to Sebastian Trueg, who will hopefully get them into K3b within an acceptable amount of time. @ Sebastian: I can't imagine copying some files from the doc folder before you package a release can be so much work. That can surely be automated with a few lines of bash script or some automake tuning. Documentation really IS important, espacially for those who don't know how it works (which is the rising majority...)
My comments are inline below. Kevin Jakob Petsovits wrote: > ------- You are receiving this mail because: ------- You reported > the bug, or are watching the reporter. > > http://bugs.kde.org/show_bug.cgi?id=100839 > > > > > ------- Additional Comments From jpetso gmx at 2005-03-07 18:33 > ------- > >> I'm new to the development end of Linux so I don't know if there >> is a place to put documentation or a specific format that needs >> to be used. > > > Currently, the place to put documentation is the attachment of an > email to one of the people taking care of this. KDE's documentation > (so also K3b's) is written in docbook format, which is an XML file > with certain tags that should be used. Like > [url]www.somelocation.com[/url] in wiki markup language it > describes the text by encapsulating it in <tags/>. If you want to > learn docbook, just look at the documentation sources in > /usr/share/doc/HTML/ or dive into the KDE DocBook Authors guide at > http://i18n.kde.org/doc/markup/index.html. I feel that DocBook would be the better way to go it will take me a couple of days to become proficient with it. > > >> I like the idea of a wiki which would move the burden of >> documentation to whoever wants to do it rather than channeling it >> through K3b development team. > > > This is a wrong assumption, because wiki documentation would also > be channeled through the development teams (until it's automated, > which won't happen for quite some time in KDE). The only advantage > would probably be more people submitting documentation because it's > easier for them. I have always found the hardest part of creating something was the initial creation. A wiki would let many people create rough drafts which could be edited for accuracy and incorporated into the documentation. We can start without a wiki (or something similar) and see where we are in a few months. What I had in mind for a wiki would be a documented description of a button to choose between ISO 9660 v. joliet and then make ISO 9660 and joilet links to other pages in the wiki. Somebody else could fill in those definitions saving us the labor. To be clear I will start with making the documentation and sending it to you. > > >> I'll do some looking around today for an existing wiki to put >> documentation on. preferably hosted by KDE but who knows where >> I'll end up. > > > You can put anything you want at wiki.kde.org which is the only KDE > hosted wiki. But I'd find it easier if you just send me plaintext > files (or docbook, whatever you like) of additions and changes to > the documentation. I then would mark them up as docbook and forward > them to Sebastian Trueg, who will hopefully get them into K3b > within an acceptable amount of time. That is what we will do then. > > @ Sebastian: I can't imagine copying some files from the doc folder > before you package a release can be so much work. That can surely > be automated with a few lines of bash script or some automake > tuning. Documentation really IS important, espacially for those who > don't know how it works (which is the rising majority...) >
There is a handbook now that explains the basics. I see no need in keeping this open, since documentation could _always_ be improved.