 |
What should an Install Guide accomplish?
These are some thoughts which came from thinking about the problem of documentation for the Devuan Linux distribution. I wanted to take some time to think an opinion through here.
I don't think a Devuan install guide should exist, and any interested people would be more helpful upstream.
|
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.
 |
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.
|
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:
|
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 > 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..
 |
Some people can plan long-term. Some people can make a daily to do list. I can do this too, but only for everyday things.
|
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.
wmctrl + Documentation >
User documentation.
Since wmctrl didn't have quality documentation, I made this myself.
For the rant on users needing to create the documentation for the software they use, see:
|
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__ ?
Update: I've put in my 10,000 hours - update
|
Lately I've been reviewing my skills and interests, and sketching out what I'm interested in learning and accomplishing.
Malcolm Gladwell was on The Hour, and he talked about his "10,000-Hour Rule" from his book Outliers.
