Open up the wiki (DSL docs badly needed)
Forum: DSL Ideas and Suggestions
Topic: Open up the wiki (DSL docs badly needed)
started by: Winter Knight
Posted by Winter Knight on Aug. 27 2006,19:03
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)
Posted by mikshaw on Aug. 27 2006,19:39
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)
Posted by roberts on Aug. 27 2006,20:03
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.
Posted by mikshaw on Aug. 27 2006,20:44
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.
Posted by Winter Knight on Aug. 28 2006,12:02
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.gzOn 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.
Posted by mikshaw on Aug. 28 2006,13:24
| Quote |
| It is oouser.tar.gz, not ootar.gz |
That's not really a misspelling or a typo. It was written in the early days of UCI, when there were also *.ci extensions that did not include the user.tar.gz file. The file was a separate tar.gz mydsl package. The 'oo' in this case stands for Open Office, because it was the user.tar.gz for the Open Office extension.
That's not to say that this article does not need some work...just explaining the filename =o)
With roberts permission I can make that a bit more clear, and also the bit about the cloop limit (maybe specify which versions of DSL have what number of cloops, if i can recall)
EDIT: here are a couple of suggestions about things I can't change myself:
Category:MyDSL should be a subcategory of Documentation.
The main page should be modified to list "Documentation" as a main link rather than its current status of being what appears to be a static header. I know it's not static, but it appears that way. Tables of contents have always been set up, and with good reason, with main categories being most prominent and subcategories being recognizable as subcategories. Take the numerous How-to pages available for example. They are uniform, with a main category as a prominent clickable link and its subcategories slightly less prominent. In this way there is no question that going to the "Documentation" link will also show each Documentation subcategory below. If the Wiki main page is to keep its current layout, then every Documentation subcategory should be listed in the box labeled "Documentation" so the reader does not have to go in circles to find what he's looking for.
EDIT2: I found the message concerning what not to put in the wiki to be a little extreme, and I don't plan to follow it more than loosely. Including general linux information in the DSL wiki is vital for a new user, particularly when the distribution itself has no room for the general linux docs that are commonly found in other distros.
Posted by Winter Knight on Aug. 28 2006,14:25
I knew about .ci extensions, though when I started writing extensions, at about DSL 1.5, they no longer worked. I never saw oouser.tar.gz, though. Then again, I keep track of my finances with firefox and leafpad.Thanks for the history lesson, mikshaw. Did you notice how if oouser.tar.gz was replaced with user.tar.gz, that that sentence would still make sense? It would still be an equally valid and appropriate point about ucis being read-only.
Posted by mikshaw on Aug. 28 2006,14:32
yes, it would be applicable to today's uci package. I would also like to expand on the use of the user.tar.gz file (how it is essentially a second mydsl extension) and the shell wrapper.
Posted by mikshaw on Aug. 28 2006,16:24
I've begun adding articles that I believe will be very useful to the new user. There is a new subcategory in Documentation which will list as many configuration files as I feel compelled to write about, I will be adding more to the Apps category, including brief descriptions of DSL applications (at least those that I know something about), and I will add a new category for "DSL_Tools", which will explain the tools that were written specifically for DSL.That's all I have planned for now.
Posted by odradek on Aug. 29 2006,02:55
I just wanted to voice my agreement with the original post. I edit wikipedia all the time, and the day I started playing with DSL, I looked at the wiki and thought, I can make some contributions here. But then I found I couldn't.Opening the DSL wiki up to anyone to edit might not be the answer ... dealing with spam and vandalism is the biggest frustration I have with wikipedia, and they have tons of folks devoting all their time and effort to combatting it, which I'm sure is a job no one wants to take on with the DSL wiki. My recommendation would be put some contact info on the wiki about how to get an account created, and tone down the threatening language in the "how to use this wiki" page. I do believe it would be best to set enough obstacles to creating an account to discourage the spammers and vandals, but at least make sure the well-intentioned folks aren't driven away along with them.
Posted by Winter Knight on Aug. 29 2006,09:22
John? Robert? My offer still stands. I'm willing to administer the wiki.
Posted by roberts on Aug. 29 2006,15:20
I appreciate the offer, but just so that everyone knows, I have little to do with the website, blog, wiki, and store. I would suggest to email or pm John and reference this topic.
Posted by Winter Knight on Sep. 01 2006,23:15
I pm'd John, offering to administer the wiki, and I referenced this post. I didn't get a response. Can you get a hold of him for me, Robert?
Posted by bostonvaulter on Sep. 03 2006,20:08
I also agree with the original poster. More documentation is definately needed. I would also be willing to donate some of my time to combat any spam or vandalism.Perhaps we could go the route of the german(i think) wikipedia and not allow most users to make live changes. An admin or moderator person would have to approve all changes.
Posted by bokaroseani on Sep. 06 2006,13:29
Any fresh news on this topic? Any response from John?
Posted by John on Sep. 06 2006,18:44
Winter Knight, I sent you a forum message a couple of days ago, did you get it?
Posted by andrewb on Sep. 14 2006,23:52
While trying to find the info on creating DSL extensions in the WIKI I found that the page telling how to do this isn't linked to from the front page. The category MyDSL (http://damnsmalllinux.org/wiki/index.php/Category:MyDSL) is linked to by DSL Tools (http://damnsmalllinux.org/wiki/index.php/DSL_Tools)but that is not linked to from anywhere - it should have a link from the front page. AlthoughI have a WIKI account the front page is locked & so I can't modify it. Can someone with the appropriate permission please add a link to the DSL tools on the front page. If nothing else the DSL Tools page provides a good list of the basic tool scripts - useful when setting up a system using text mode.
Posted by mikshaw on Sep. 15 2006,01:41
I thought the same about the myDSL category. It definitely should be linked to the main page. However, the main page and the mydsl page are both locked, so even with an account these issues can't be fixed. As far as I know, John is currently the only person with the power to do anything about it (Saidin has apparently gone away).
Posted by fioddor on Sep. 16 2006,10:59
Any news about John, Knite and the Wiki resurection?I'm willing to invest some effort too. I'm not committing time (availablity or ammounts) but I'm indeed willing to commit quality by following any strict cross-checked procedure that might be established.
Please, let me know how could I (we) help!
Posted by Winter Knight on Sep. 17 2006,01:10
John and I have been in contact. He has agreed to accept my offer to administer the wiki. As I understand things, he's upgrading the server, or maybe the wiki software, and getting the wiki back in working condition. It will probably be open again soon.Update (Oct 2, 2006): Got my administrator username and password. John installed a captcha image for new user registration. Parts of the wiki are unlocked, and can be edited. The front page is still locked. I'll see about making it more friendly.
Posted by Winter Knight on Oct. 02 2006,12:36
Been playing with the wiki. Added a lot of stuff to the Main Page. It appears that there was a Beta Page, which was more complete than the Main Page. I added a MyDSL category to the Beta Page. Then, using my phenominal cosmic powers, I replaced the Main Page with the Beta Page, including the link to the Beta Page. Yes, the Beta Page tried to link to itself, which makes sense if you understand the concept.I "unprotected" the Main Page discussion, which makes that page a better place to discuss Main Page alterations. Also, you can change the Main Page Beta, and I'll review and probably incorporate your changes within a few days.
Hooray! The day has finally come!!
Posted by ^thehatsrule^ on Oct. 02 2006,12:49
Yay 
Posted by mikshaw on Oct. 02 2006,14:13
I never knew about the beta page (maybe just not too observant...)It's a very good idea as long as it's checked often enough.
Thanks.
Posted by chaostic on Oct. 02 2006,15:29
w00t? 
//goes to add common errors page he wanted//
Posted by Johnnie Price on Oct. 02 2006,23:52
So, a compiled Tips and Tricks page would be useful and handy, right? Things like changing time format to 24h, removing the fluxter, how to get Firefox plugins to work properly, et cetera?
Posted by mikshaw on Oct. 03 2006,01:18
yeah...that would be nice.Unfortunately they've tried a "tip & tricks" section twice in these forums and 90% of the posts still end up being questions. Hopefully having something like that in the wiki would remain question-free and a good source of miscellaneous tips =o)
Posted by andrewb on Oct. 03 2006,03:43
A link to DSL tools:(http://damnsmalllinux.org/wiki/index.php/DSL_Tools)
is really needed on the front page, but I can't really see where it fits. Perhaps software & hardware categories need to be created, with links beneath them giving more detailed info.
A section / category with links to installation / use on specific machines would be useful (e.g. I've been thinking of setting up a page for the Toshiba Libretto 100/110).
Posted by mikshaw on Oct. 03 2006,05:10
There is a link to it in the Apps section of the Documentation category, where I think it fits well. The problem I see is that the Documentation category itself is not prominent on the main page. The link to it on the main page visually appears as though it is a label rather than a link.
Posted by andrewb on Oct. 03 2006,07:09
OK, but I think this page needs more prominence, the contents of this page are at the heart of DSL.I reported it not being linked as the "what links to here" button in the Wiki shows nothing linking to the DSL Tools page.
Posted by fioddor on Oct. 12 2006,22:20
Hi there,I've test driven the wiki edition by translating the < http://damnsmalllinux.org/wiki/index.php?title=How_To_Use_This_Wiki > into spanish (http://damnsmalllinux.org/wiki/index.php/How_To_Use_This_Wiki-es)
so
(a) the wiki tells me that I've got cookies desabled. It's not true so if it happens to you just try to upload and it will probably work. (Someone should fix this (?)).
(b) I'd like to talk to the administrator concerning internationalisation.
First of all I'd like to confirm that we are allowed to translate the wiki. Once that translating DSL itself is quite much more difficult (both the translation and the its management), translating at least the available documentation would speed up the adoption. This has been suggested and discussed several times and in the spanish forum there are several volunteers for the job.
On top of that I'd like to agree some strategic issues related to this like translation vs. parallel wiki (again a coordination issue) and naming convention (I've started using the same as in aMule project: english page name+"-es" appendix, but it somehow limits alternative solutions and searches). How to handle the categories would be another topic (do we just create 1 category per language or do we translate them all or do we appendix-dupplicate them all?).
Posted by andrewb on Oct. 24 2006,01:44
I have reorganised the Installing DSL category & added a sub-category 'Specific Systems'. The thought behind this category is to accumulate pages specific to individual systems (e.g. I have a Libretto 100CT & will write that page). This would be a really valuable resource for people looking to install on a particular hardware system. It would replace the thread that was running somewhere on what laptops sucessful installs had been done.The Main Page 'Special Installs' category is a bit of a confusing link & should probably be renamed asap to better reflect the contents of the category - see the main page beta for a suggestion.
Posted by WDef on Oct. 30 2006,15:49
Well I've just been doing my duty and hacking away at the wiki"making extensions" (.dsl and .unc) - a bit rough but it's a start.