DSL Ideas and Suggestions :: Open up the wiki (DSL docs badly needed)
DSL is badly in need of more documentation. Every twentieth post I read is a new user complaining about the lack of documentation in DSL. When I was a new user, I would have been turned off by DSL's lack of documentation, if not for the fact that I was a linux noob as well, and didn't know any better.
What documentation there is is spread out like a slut at Mardi Gras. How to make a DSL is a pdf file in the subdirectory of current. Tar.gz and uci is in the wiki. And unc is in a reply to a barely related post in Release Candidates. The difference between what these extensions are can only be inferred from a variety of sources.
The wiki has some info, but it is seriously out of date. Bootcodes are incomplete, as there are more now than there used to be. There are some wireless cards listed, but I can't add mine to the list because it is not a real wiki.
The main source of info for DSL is searching forums and asking questions. Searching forums and asking questions is fine, but it is relatively slow, and should not be a primary source of info. Also, when people answer questions, it doesn't last that long. Sure, it stays in the forums forever(?), but it will be asked again and again.
As a rule, a typical user should be able to install and start using a distro without asking any questions. Everything necessary, including potential roadblocks, should be in the docs.
The single, easiest thing the developers can do to improve documentation is opening the wiki. In its current state, it is not even fit to be called a wiki.
I predict that if the wiki was opened, documentation would just flow in. Some people will copy stuff right out of the forums and pdf docs. Others will write articles that no one knew needed writing, but after anyone reads it, will wonder why it wasn't written before. The bootcode list will be complete. The working wireless cards list will slowly get bigger and bigger. Whenever anyone asks if their wireless card works, or how to make a uci, or even sometimes why they are getting a certain error message, we can just point to the wiki. I can finally correct mikshaw's spelling error. (ootar.gz)
I've written only one wiki article, and I don't see that specific typo? Perhaps your browser is displaying "*." as "oo"?
The *.uci, *.dsl, and *.tar.gz differences are mentioned together at the top of the main myDSL page in the wiki.
My personal complaint about the wiki is that navigation is poor. Many subjects are available only by either knowing the URL or by first going to a related subject, rather than having the usual table of contents. The myDSL category is a good example of this. "Category:MyDSL" is the top level of all subjects related to MyDSL extensions, but in order to get to Category:MyDSL you first have to go to the subcategory Installing_MyDSL_Extensions (which for some reason is a different name than the MyDSL:_Installing_Extensions category).
I have no idea how to reorganize or link within the wiki, so all I can do is complain =o)
The Wiki was closed becaue it is in need of an administrator.
The Wiki was closed beause of the constant barrage of spam and objectionable links.
That is why it is needs an administrator.
Each time we find a volunteer to try to maintain it, they find it an overwhelming and thankless task with more time devoted to clean up of junk than actual maintaing of content. A vicious circle.
Many other Wikis have closed because of this unfortunate situation..
I do totally agree with your sentiments.
John needs to make some decisions of how to proceed.
I just spent a little time reading the wiki how-to (i'm an old fart who hasn't done any online web page creation since Geocities was cool), and I'm a little more comfortable with it now than I was an hour ago.
I'm not volunteering to be an admin, or even to be dependable =o), but if you don't mind I'll spend a little time here and there making small edits and additions. That's better than doing nothing at all, and since i already have an account I probably should use it.
About the spelling error, my mistake on two counts. The error is in "Creating a UCI Extension", written by roberts. It is oouser.tar.gz, not ootar.gz
On to more serious subjects, roberts, did you guys use CAPTCHAs? I noticed that the links are followed by robots, without the norel attribute. I've heard that norel isn't particularly effective (though it can't hurt), but I've heard lots of good things about CAPTCHAs.
I officially volunteer myself to administer the wiki. I've been using DSL since 0.9.0.1, and I've written several extensions since April. I've also answered several questions in the forums. I think documentation is very important for every open source project.
Next Page...
original here.