documentation

All posts tagged documentation

Documentation is important.

However, many mature projects have part-time or overworked staff, or are built of a loose collection of volunteers. Whatever the case may be, there are times when documentation is old and broken, or poorly-designed and hard to use.

This document goes over some basic ideas for creating a new "better" project.

Do note that such a project is just as vulnerable as all of those old ones. Community participation is by far the most important element.

Continue Reading

Outliers, by Malcolm Gladwell - cover

It was Aug 2009 when I wrote I've put in my 10,000 hours. Rather than updating that post, I'll save it for history and completely rewrite it.

A long time ago, Malcolm Gladwell was on The Hour, and he talked about his "10,000-Hour Rule" from his book Outliers. When I saw that interview, I realized I've put in my 10,000 hours on a couple of topics now.

However, when I now think back on it, I see a big difference between the "expertise" 10,000 hours of intuitive interest, versus 10,000 hours of practice with a learned skill.



Continue Reading

(I'll return to update this topic as my attempts continue)

The infoAnarchy wiki was a notable resource for Peer-to-peer software and other information.

Most of the major contributors and administrators had left a long time ago.

It had been down for a very long time. Erik Möller aka Eloquence left it to die long before this downtime.

I noticed it's been restored, but the database has been locked due to spam concerns.

Those spam concerns exist, of course, because it's MediaWiki install hasn't been updated and basic precautions haven't been taken. Because it's been left to die. Well at least some time was taken to get this version of things running.

There is a shitty mirror, but shitty mirror is shitty so I want to archive infoAnarchy before it's gone for good.

Continue Reading

Ok, so I haven't been writing here at all. Why? Well because I have too many different "systems" out there which each get a piece of my attention. So sometimes one of those systems suffers.

I do actually have 40-50 people a day who read something within this blog. While that isn't the quarter million a month from the good old days it's still some people who might care. Or not, I don't actually know. There's no real social aspect to blogging like it seems to exist elsewhere. Well that's something I'll ponder over sometime later. I'm antisocial anyways, so it's low priority.

So seeing as there is at least "some value" in this place, I really should be thinking about it more often. So that's why I'm back and why I'm writing this.

I suppose I may as well do one of my huge essay pieces, since there is just so much background which would need to be understood for a reader to actually "get" what I'm going to try to get across.

Continue Reading

Hobby software being what it is, there is no centralized place to have documentation.  Everyone turns to search engines, which means that user-contributed documentation can go anywhere online.. and it doesn't matter where.

This means that any project which attempts to centralize user documentation will be forced to reach out onto the net and cache their contributions from outside sources.  freedesktop.org is our timely example! (wmctrl)

If the original user documentation is updated, or new documentation is created, then that central resource goes out of date.

But is there hope?  Not at all!  =)

An enthusiastic user can only hope to contribute directly to the project.  Failing that, they have private notes or hopefully blog.. and that's one big mess.

Oh well..

rss2email >

Followup YouTube+RSS-related stuff is in Atheist YouTube channels, now gone

Warning: This post contains everyday language. It's one thing to be polite, but I need to stress the importance of the destruction of usability-apathy. There's no room to be nice here.


I was intending to do a decent post every day, but I got really burned out. Why? I've been struggling with several different programs over the last couple of weeks. I've been sick and tired of the clumsiness that my apathy has allowed.

I think everyone has a sort of apathy towards usability issues. We take them as excusable or as some sort of status quo "that's just the way it is". I'm sick and fucking tired of that. Seriously.

Continue Reading

wmctrl user documentation.

  • These notes were created under wmctrl 1.07

    • I did not record the distribution (or version) that I was running at the time. Perhaps Unity Linux or PCLinuxOS.
    • wmctrl's changelog claims that 1.08 was released 2005-10-10, but it does not have a download link to that version.
  • NOTE - The transition from one format to another might mean there are odd mistakes (missing spaces, incorrect characters) in this document. Please Contact Me if you have any issues or you'd like an update.

    • This is probably the best piece of documentation on wmctrl and I demand perfection out of my docs. I'm the kind of guy who will put two spaces after a period in HTML (where the second is discarded).
  • An early version of this was partially-mirrored at http://www.freedesktop.org/wiki/Software/wmctrl/ (with my permission)
  • For the rant on users needing to create the documentation for the software they use, see

Continue Reading

One of the things that's been a real killer for me using most wikis has been the syntax.  None of them get it right.

MediaWiki has been bearable, and over time I've grown used to it.  The problem is that nobody agrees on a remotely similar syntax.  There were some early efforts to create a generally agreed-upon syntax, and it did fairly well.. but it's still not used everywhere.

I'm not just talking about wikis, but about markup languages in general.  Even something like Ruby's RDoc decided on its own syntax.

And they're all wrong.  Seriously, who thinks  that __this is italicized__ ?

Continue Reading