One of the biggest drawbacks to any software is always bad or weak documentation.  We computer users continue to have questions because the software geeks can't write, nor can they explain.  However, without detailed and exhustive documentation, there will always be too much confusion and too many questions.  There is never an excuse to not write things down as the programming is written.  (For pity's sake, just throw it all into a big pile and let an English major put it into useful, readable form already!)

Let me point out a specific  area where problems occur but where documentation can help.  The problem of each distro disabiling or crippling some feature or other either means that the particular program designer didn't think it was necessary to address that properly within the program itself, was ignorant of the problem, or just didn't care.  Programmers must stop using the flaws of the OS as excuses.  If you can't do something, admit it and document the reasons why, as well as tell the user how to get around it.  (Always remember that the program should stand alone as much as possible anyway, so too much reliance upon the OS is a bad thing.)

The heart of program acceptability and popularity is an extremely intuitive UI.  Any flaw in that (and who doesn't make mistakes?), and there is an absolute necessity for good documentation to bridge the gap.

I suggest that work always be stopped on any programming roadmap until proper documentation is created.  Good and comprehensive documentation will always help with the ongoing process, both by the programmers and the testers and users.  Right now the current user handbook is unacceptable and needs serious work.  Now is the time to fix that.

Thanks.

Right now, the devs need some serious volunteers to help WRITE the documentation. I helped write the 1.4 handbook, but due to impending circumstances I'm unable to help with 2.0. I found it an extremely rewarding way to contribute to this project, and would recommend it to anyone.

I'd very strongly suggest that ANYONE who is unimpressed with the current state of documentation should contact the Rokymotion team at amarok-promo@kde.org and find out how they can help.
Writers in all languages are needed.

Criticism really can't be given until help has been offered - the devs are coders, not authors (as has been found in the past - you know it's true, guys!!) and volunteers have been pretty thin on the ground.

You know what to do.

While somewhat off-topic, I couldn't agree more to the first part of the last post.

The last part, however, about criticism is wrong.  The place for critical appraisal is before the product is pushed out the door.  This is the very reason that there is so much sub-par software associated with Linux.

I wouldn't have started the discussion if I didn't believe that Amarok is poised at the cutting edge of its genre of software.  So let's take some time to first see where the problem with the documentation is coming into the picture and discuss that, so that we can at least solve the obvious missing parts.  I might suggest for everyone's consideration that the vast majority of forum issues could have been non-existent had the documentation been clear and/or the program development had taken a different course.

Of course, my comments were meant as somewhat generic in nature, and I suggest we keep it that way.  Believe me, I understand the reaction embarrassment can cause on the part of those close to the subject matter.  But perhaps we should get back to discussing the basic philosophy of software design and software support as clearly displayed and intended in user manuals.

In particular, since you are close to the documentation part of the discussion, you may wish to contribute by describing the current process that was used to create the existing handbook.  In particular, how is the information gathered, and what is the current philosophy about the layout and subject matter that has brought the handbook to the state it is in currently?

Just think of me as representing the thousands who want to encourage the next step in the ongoing process.  I'd sure hate to see the next release come out without the previous problems fixed, and I know many feel the same way.  There is such potential in Amarok.  It would be a shame to waste it with so many users hoping for a final solution.


(By the way, dangle_wtf, many mothers admit that the worst pain they have ever experienced is the pain of a kidney stone.  Men who have experienced it know definitely what real pain is all about.  So have all victims of torture.  Comparing pain is actually pretty silly.)

My involvement with Amarok documentation came about as a result of frustration at helping people in the #amarok IRC channel with the same problems over and over - so I started padding out the Wiki, as I was more comfortable with content than having to learn docbook. Others did the dirty work.
Get to know your product - make notes as you install the program, what issues you had (if any) and any distribution-specific information you encountered.
Note the steps you need to perform to start using the program, from launching to working through any set-up wizards, building collections etc.
Work through each menu, summarising what every option does, you can flesh this out later in more depth.
And so on - it's not difficult, just time consuming, and I don't have that time anymore.
Generally, you'd work closely with others in the team to expand your own knowledge of the program, and you'd keep up-to-date with changes being made.
Apart from that, the only real requirement is to be able to write coherently in whichever language you choose - doesn't have to be English, as there are others who can translate.

As an open-source project, contributors do what they are able - if there's nobody willing to write documentation, it doesn't happen, apart from possibly a rudimentary "getting started" guide. The handbook follows KDE documentation standards - there's plenty of information on formatting at http://l10n.kde.org/docs/

re: my sig - it's actually in response to another sig on this board - as an exercise I'll let you find it for yourself. Suffice it to say I know what *I* have experienced.

Please allow me to offer my thoughts on  program documentation. First, let me tell you about me. I am 67 years old, retired and not really knowledgeable about software development or the tools and language that drives a program. Wish I did, but it "ain't gonna happen" at this stage of my life. I do use computers a lot. I love what they do. I envy the folks who have the talent to make the computer "dance for them". My lack of knowledge does not scare me from trying to learn, especially when it comes to listening to my music. So I'll get to my point regarding documentation.

The usual failure of many help or tutorial manuals is a failure to give a crystal clear overview and introduction. The K.I.S.S principle applies here--- Keep It Simple Simple. Start at the beginning. Start at the beginning. Do not assume I know how to do anything. I don't.  But I try to learn. (Often, I must learn by a trial and error effort unfortunately.)  Tell me about the features and benefits of the program from the beginning.

The basic purpose of the program, the way the features of the program work, the requirements of the hardware, the additional, other software needed, an explanation of what each major part of the program does and anything else that will guide the user of the program. A music management and player program has use by  most people who lack the insight about the language and organization of the programs code. They want to use the program if it does what they need, but they need to be shown that a program meets there needs as clearly as possible.

I close and repeat my main thoughts: Documentation should start at the beginning and it should be keep as simple as possible for the intended audience. When a manual is written for Amarok, it should be written to an audience like me, at least the part at the beginning of the manual. Once I have the basics the technical part of the software becomes really useful and important.

Right now, I'm trying to understand how and why Amarok has the design it uses and why this program will help me listen to my music. All this research keeps me from listening to my music. I wish there was a kid around to get help. The young sail through this stuff so easily. So, folks, when you set down to help folks like me, the end user, remember what we really want to do. We want to use the software, not write it.

(I thank you all for your effort. It is remarkable what you all accomplish. Thank you for what you have done to help me listen to my music.)

Catclaw, I hope you will consider helping us with the Handbook. Work is now beginning, and I hope that 2.2.2 will be an excellent time to restart the effort.

irc://irc.freenode.net/rokymotion
https://mail.kde.org/mailman/listinfo/amarok-promo

Join us!

Valorie