Fri, 27 Feb 2009 10:41:14 +0000 Quoting "Herbert Poetzl" <herbert@13thfloor.at>: > okay, I would like to get into details here, especially > the following points: > > - does not project a very professional ethos > - comes across as a tad bit arrogant > - very hard to pick up from scratch > > could you (all) please elaborate on them, as I do not > fully understand why that would be so ... > "Comes across as a tad bit arrogant" it really is just a tad bit and will probably change as the project progresses. I sometimes detect a "why don't people know this already?" attitude. It's easy to fall into this feeling when directed the wiki and then thinking to ones self, "Why didn't I find that?". Many people will not bother to peruse documentation before asking questions, I do though, but still there are many times I can't find solutions to my problems in vserver documentation. There are some characteristics of the documentation and of linux-vserver which are part of this problem. On to "very hard to pick up from scratch" there are two things that come to mind. 1/ nature of documentation The config is a bit tricky to say the least, and combined with documentation where it's often necessary to find many different sources to accomplish one task. As has been pointed out in this thread, for a configuration task one might access: * the wiki, to see if there's a good description there. It might turn out to be best described: - in the FAQ - on a documentation page - in a howto * the old wiki - to see if it's clarfied or defined in more simple terms on a legacy page * the great flower page * mailing list archives - to see if it's been discussed in a more accessible way recently * google * IRC - because I still haven't got what I'm looking for and now fell like a real dumbass Sometime at that point I'm re-directed to wiki page I haven't spotted, or one I have but didn't grasp, enhancing the dumbass feeling. I should certainly add though that there have been vast improvements in documentation since I started using the project. Perhaps I should contrast this with the process of getting relatively complicated database replication tasks sorted on MySQL. * Read the MySQL docs * read some howto's to clarify Another example might be that the page one is redirected to from http://linux-vserver.org/Frequently Asked Questions. http://linux-vserver.org/CPU Scheduler 2/ vserver config happens in many different places and has changed format As an example, I've wanted for a while to set the default place where new vservers are created. I found /etc/vservers/.defaults/vdirbase, but it took a while. The "Great flower page" says "a link to the default vserver rootdirectory". This is not verbose enough to be found by any search engine, and does not describe the processes the file is involved in. "does not project a very professional ethos", is basically all the points above plus there are some characteristics of professional looking websites. 1/ Development content is seperated out from the main site 2/ Documentation content is seperated out from the main site 3/ Documentation and development content are in seperate places 4/ The front page is about advertising the product and blogs new innovations As an example of how the vserver website doesn't look professional, have a look at the top level links on the site and what you find there: ABOUT: Overview - Technical discussion of virtualisation - not too friendly a start Paper - Technuical discussion of vserver - not too friendly News - last updated Nov 2006 Developers - I like this page, probably not an appropriate place though Donations - one appropriate link on this section GETTING STARTED: Downloads - Fair enough FAQs - "We are currently migrating to MediaWiki from our old system,.." Documentation - "We are currently migrating to MediaWiki from our old system,..", this definitely does not look professional. Support - "This page is not considered complete", this definitely does not look professional. Getting back to documentation, this is the most thought I've ever given to all this, and it's spawned a suggestion. The documentation of the configuration files (currently great flower page) needs to be expanded to have the following characteristics: - Versioned: a different URL head for each version of vserver the pages relate to (new versions are created by copying the content of the previous version and ammending) - Verbose: instructions for use with practical examples. - Contextual: a record of how and when Linux-vserver uses this file and for what purposes I suppose I'm asking for a reference manual, if there was an appropriate web based structure to create this I would be happy to contribute. In case of sounding too negative about everything, I would like to out that vserver is brilliant, essential to my work and companies I work for. I really hope we get some positive movement from this thread and find a way that users can contribute to documentation more by restructing, get the developers lots of steady cash, promote Linux-vserver to a wider audience and get the project better integrated into the mainline kernel and distributions. Cheers, == From Ben Green