Re: KTorrent Manual

James Tyrer <jrtyrer@xxxxxxxxxxxxx> · Tue, 10 Jul 2012 19:52:22 -0700

On 07/10/2012 05:28 PM, Duncan wrote:

Burkhard Lück posted on Tue, 10 Jul 2012 21:24:16 +0200 as excerpted:

Am Dienstag, 10. Juli 2012, 21:20:46 schrieb Sian Mountbatten:

This, apparently, is some kind of joke, because the manual consists of
a list of features, and that's all.
Does that mean that no manual has been written?

Yes.

Concise answer, correct AFAIK, but not very satisfying for those of us
who like a bit of detail...

Here's the deal.  Free/libre (free as in freedom) and open source
software (FLOSS) is in an interesting situation in regard to
documentation.  Much of it is done by volunteers, and documentation kind
of falls between the cracks.

Those who write the code and share it with us may be quite good at
coding, but many aren't so good at documentation.  Coding is their
interest so what they tend to do when they have free time to volunteer.
Besides, the people writing the code aren't normally the best to document
it anyway, as they're too close to it, and most of it seems intuitive to
them, since they wrote it the way they thought it.

Well not exactly.  Those that write the code need to write the actual 

documentation.  That is not the same as a tutorial style manual that 

explains to a user how to use the application.

The problem is that there isn't really any place for this documentation 

of the KDE project.

That leaves users.  But there's a problem there as well.  Either users
don't know enough about how it works to write the documentation, or by
the time they do, they no longer need it, so it's not so important to
them.

Yes, and that is my point.  A user that is skilled in writing can only 

write a good manual if full documentation is available to use to do so.

I am fairly good at technical writing, but, no matter what style I write 

in, I can not do so without the documentation.  I am a programer so I 

could deal with terse and/or rough documentation, but there is no good 

way to deal with no documentation.  This is why my tutorial on how to 

install KDE from source has not been redone -- the outdated one was deleted.

--
James Tyrer

Linux (mostly) From Scratch
___________________________________________________
This message is from the kde mailing list.
Account management:  https://mail.kde.org/mailman/listinfo/kde.
Archives: http://lists.kde.org/.
More info: http://www.kde.org/faq.html.