Subject: Re: [vserver] Roadmap and Future ...
From: ben@bristolwireless.net
Date: Fri, 27 Feb 2009 10:41:14 +0000

 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