All posts tagged documentation

spiralofhope logo 768x768-white-background

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

spiralofhope logo 768x768-white-background

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.

See also:

Continue Reading

spiralofhope logo 768x768-white-background

Documentation >

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. is our timely example! (wmctrl > wmctrl user documentation (examples))

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

spiralofhope logo 768x768-white-background

rss2email >

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

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

spiralofhope logo 768x768-white-background

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