KTorrent Manual

[Duncan]

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.

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.

That leaves people being paid to do it, which is where commercial 
servantware gets its documentation.  But freedomware is generally either 
free or quite low cost, depending on where you get it, so the money 
doesn't so much come from users paying as it normally does with 
commercial servantware.

Of course commercial servantware has its own problems in this area and 
often, anything beyond the bare minimum is an additional purchase 
anyway.  Of course, that lets freedomware compete again, to the extent 
that both users of commercial servantware and freedomware are often 
willing to pay for documentation.  Which is where publishers like O'Reilly 
come in with their books on software, much of which is on freedomware, 
tho they write books on servantware as well.  But people don't so often 
pay for what they think they should be able to figure out themselves, so 
most of those books are on more complex software, scripting languages 
like bash, python, perl, etc, or platforms such as GNU/Linux or MS 
Windows in general.

Meanwhile, there is /some/ sponsorship, and back in the kde3 era, someone 
sponsored some pretty decent kde documentation.  But that was for kde3, 
and a lot has changed in kde4, so much of that documentation no longer 
applies.  It's being updated, but that takes time, and sometimes the 
changes come fast enough the people doing documentation can't keep up 
with updating what's already written, let alone expand to not yet covered 
software.

Which is why we get "manuals" that are little more than lists of 
features...


Meanwhile, a lot of the documentation is now online in the form of wikis 
or the like.  KDE has both techbase, for the technical side of things, 
and userbase, for the the less technical user side of things.  That's 
where a lot of the new stuff is going, tho some of it eventually makes 
its way into the various manuals, etc, as well.

So:

1) Try checking the http://userbase.kde.org wiki.  There's probably at 
least a brief description of the software there. (I haven't actually 
checked for ktorrent, tho.)

2) As you get more familiar with kde software (including ktorrent) 
yourself, consider adding your own contributions.  If you note, there's 
various tutorials, photo and video-based howtos, etc.  You don't have to 
limit yourself to "boring words" if you think photos or videos will work 
better either for you or for others looking at what you've contributed, 
AND, you don't have to be an expert to add a few details here and there 
where you already know how it works and want to make it easier for others 
than it was for you.

3) KDE has a lot of contributors, both formal and informal.  Just because 
you can't write programs doesn't mean you can't contribute art, or help 
with userbase, or be a regular on a mailing list or two, answering 
questions where you can (my chosen contribution, informal, I just started 
doing it...).

KDE is freedomware and you don't /have/ to contribute back in ordered to 
just use it.  Many people, I'd say most, are simply users.  But it's 
really rewarding to pick a project or two that you want to be a bit more 
involved in, and pitch in where you feel comfortable and see a need.

A bit more than a decade ago I switched from Windows to Linux and started 
looking around for my little corner to help in.  I'm not a coder, so that 
wouldn't work, and not an artist, so I couldn't much help with icons, 
artwork, etc, either.  But I found a project I was interested in (pan, a 
gtk-based nntp/news client, FWIW), and joined the mailing list.  Years 
later the primary developer lost interest and the project was nearly 
abandoned, but I and a couple of others stayed around on the mailing 
list, continuing to help anyone with questions, where we could.  I'm sure 
I wasn't the only one thinking it was about time to shut out the lights 
on the way out, as the project was abandoned and it was beginning to get 
hard to continue to build and support it on newer distributions.

But you know what?  Because I and a few others stayed around, forming 
that small nucleus of continued life, about time we had lost hope, a new 
developer got interested, and at least started collecting the bug fixes 
and build-fixes the various distributions had made into a single 
repository that people could download and build from.  Then someone else, 
involved with gnome as a translater so with commit rights, but not a dev, 
got involved as well.  That gave the project a new dev to at least keep 
things working, and someone to commit his changes to the official 
repository and keep it working.

Then that drew in more developers, including one with some real time and 
skills to commit to the project and thus implement some badly needed 
missing and new features, and today the project is alive and thriving 
once again!

All because I and a few others, even without developer skills of our own, 
continued to keep the list alive, helping where we could with what we 
were sure at one point was a dead project, just biding our time out of 
old habit, more than anything.

Then a few years ago I joined a couple kde lists, and contribute here as 
well.  But I'm still a bit new here and don't have the deep knowledge of 
the after all much broader project that I do of that original project.  
But I still contribute where I can, both learning myself, and helping 
others.  And you know what?  There's simply no feeling on earth better 
than the feeling you get when someone says hey, thanks, you explained 
something in a few posts that I had spent months looking for! =:^)

Well... nothing on earth better... expect perhaps knowing that I played 
quite a big part in saving a project I loved from extinction! =:^)

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

___________________________________________________
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.