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

soh-golden-triangle-and-fibonacci-spiral-edited-profile1.png

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

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

wmctrl + Documentation >

User documentation. [ 1 ] An early version of this was partially-mirrored at https://www.freedesktop.org/wiki/Software/wmctrl/ (with my permission)

Since wmctrl didn't have quality documentation, I made this myself.

Continue Reading

Footnotes

^ 1 An early version of this was partially-mirrored at https://www.freedesktop.org/wiki/Software/wmctrl/ (with my permission)

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