Ubuntu documentation in shreds

An ambitious plan to smarten up the online documentation for Linux distro Ubuntu has ended in failure. Dubbed the Summer of Documentation by the Ubuntu forums beginner team who devised the plan back in June, the goal was to clean up the Ubuntu Community Wiki. The documentation wiki had "fallen into a huge state of disrepair …

[Anonymous Coward]

Demonstrates the problem with open source

.....that people will only reliably commit and work hard when they're getting paid. Volunteering is all well and good but if you want a consistently decent product, with all the trimmings (support, comeback if it screws up etc) then you have to pay for it. It's only when ideas like Mozilla get into bed with big business that it starts to work.

Paris, cos she never pays for anything either and, not co-incidentally, doesn't have a clue how the real world works.

[Anonymous Coward]

So

how is this different to any other open source 'documentation'? The poor quality of help files is one of the big issues that keeps the masses away from open source.

[Tanuki]

Herding cats.

Herding cats is generally acknowledged to be a futile act. Same goes, it seems, for herding prima-donna programmer/documentation-writer types.

My rule for business-grade projects is the old 80/20 rule: 80% of the effort goes into designing and documenting, 20% into coding. The 'user guides' largely get written before anyone cuts code.

Think like a property-developer: your architect initially produce the spiffy fluffy-edged idealised renders that show the world what the building/bridge is going to look like. Then you get a horde of people to spend time sweating over AutoCAD to produce the plans. Then you recruit East German bricklayers, Chinese roofers, Polish plumbers and Moroccan plasterers to put it all together. And a few Home Counties wide-boys to sell the results.

The open-source community is fundamentally lacking the architects, the AutoCADders and the Home Counties estate-agents. Polish plumbers and Chinese roofers we've got. But we don't let them *plan* shopping-centres.

[Vincent]

Not backed up?

Why wouldn't you back up that stuff before making changes to it? Especially the help files, which for Ubuntu (And any other Linux distro) is probably one of the most important things for raking in new converts.

[gareth]

community wiki

i don't think i have ever used the official wiki

ive used www.ubuntuguide.com a few times (its rather good)

and i use the forum all the time but the offical wiki has always been useless

[Alan Donaly]

Dull is not the word

I would rather eat a bag of toenails. I have done it(documented code I mean not the toenails) but the memory is very evil. It's interesting though to get any sort of insight at all on this in the not too distant past open source projects would start something like this it would go nowhere and you'd never knew what happened possibly this time we may find out. Personally I always blamed it on developers liquored up on tequila and getting overly ambitious.

[Daniel]

you mean ...

... that documentation-after-the-fact is usually crap and can't be fixed by putting a wiki and pointing the hive-mind at it? say it's not so!

[Anonymous Coward]

SuSe 1, Ubuntu 0 ???????????????

When you have printed documentation to produce, as Suse has traditionally had as part of its boxed/retail product, it tends to focus someone's attention. Perhaps the Ubuntu community should look at that approach?

How much useful documentation has been included with Windows for the last decade or so?

[Anonymous Coward]

Not just open source

Let's face it, all developers hate writing documentation.

How many commercial environments do you know where the documentation is accurate and up-to-date?

[Nate]

Re: Demonstrates the problem...

@AC: Uh. No. Do not pass go, do not collect $200.

IMO, you have zero clue about the industry. I don't think there's a single company, or open source project that has produced a "consistently decent product, with all the trimmings."

Ever.

Based on my own experience, I'd even go so far as to think that most "paid for" applications, operating systems, whatevers have LESS support, documentation and loyalty to their customers than most open source projects.

Go do a little research, and then tell me if F/OSS groups are less reliable. I don't think you'll be able to do that.

[Anonymous Coward]

But

Microsoft software engineers get paid and look at the dross they produce.

[Jon Cutting]

Re. Demonstrates the problem with open source

".....that people will only reliably commit and work hard when they're getting paid."

People seem to me to work the hardest when they're enjoying what they're doing. I wouldn't claim to be a world authority on the subject but I've come across many disinterested and uncommitted people who were working at tickover and being paid at the time.

[Andy]

@ "demonstrates the problem"

Sorry, can't agree with you. Don't you think that the millions (?) of lines of code that go to make up a Linux distro were "hard work"? Most (not all) of that was done by people who weren't getting paid.

Or what about the millions (?) of pages of Wikipedia, for example? Were people paid for that? Granted, much of it is tosh. But much of it is not tosh. And it didn't write itself.

While I'm at it, I'd like to take issue with the idea that the Ubuntu documentation was unusable. I was certainly using it. It needed updating and improving in places, sure. But it wasn't useless. So this is not a disaster.

[Mike]

Documentation truths

1) Good code is self documenting.

2) Everyone believes they write good code.

3) You don't want to put your name to bad code by documenting it.

Therefore no code gets documentation. Also this has nothing to do with being paid, unless you are being paid specifically to write documentation. I get paid pretty well and haven't written more than 10 pages of documentation in the last 20 years. (see #1 & #3).

Tagging this as an open source problem is just lame. This is an industry wide problem, and only someone who is owned by their employer wouldn't know that.

Now get back to work you still have 20 lines of code and 10 pages of documentation to finish before the end of the day, and stop complaining, after all it's an honor for you to work here, you should be paying us.

[Kanhef]

A frequent problem

with FOSS: the documentation is poor to non-existent. For it to really become mainstream, there needs to be well-written manuals and help files that the average, non-techie user can understand. Having to hunt through forums to find the changes to xinetd.conf needed to make something work is not acceptable.

[SilverWave]

Not a show stopper as you can just google "Ubuntu [Problem]" and you're sorted.

The rule is, 99% probable fix within the first 10 results.

To raise the odds look for hits from ubuntuforums.org/

^That's the beauty of FOSS, lots of people helping each other :P

TBH I have found the documentation on the Ubuntu site to be good, at least up to paid software standards.

If you want more - go buy a book and encourage the writing of more :)

[Anonymous Coward]

It's Ubuntu ...

... so what did you expect?

Come over to Fedora and see what a real distro looks like.

[Tom]

@ Demonstrates the problem with open source

They could use the documentation system that Microsoft uses...

Tell everyone to go buy a book.

[Linlu]

Lack of documentation doesn't only affect open source

I have seen it time and time again, by those who get _paid_. I'd say 70% of the people I have worked with disdain documentation. They usually find some way to weasle out of it. If and when the code or a process is documented, 90% of the time it's just a pseudocode outline of what the code is doing or the repetition of the labels on the screen. I don't see why it was done, what the tradeoffs are, what the impact of a choice is, etc. Basically 90% of documentation I have encountered in commercial products is useless drivel put there to check off the box.

[Doctor T]

Get to work, Canonical...

Sorry, but the boys at Canonical are to the point where they are making money off Ubuntu, so they should do/fix this wiki problem of theirs.

They already inherit 90% of their product for free from the community, which they now sell in stores, and obviously are making large deals with the likes of Dell. I'm not quite clear as to why they should be getting more handouts from the community. It's time for them to contribute.

Note I'm not bashing Ubuntu, or Canonical, for their distro. It's quite nice and I use it in several places, but to think that a bunch of unpaid volunteers should help their product-specific wiki out, when they are making money off those efforts, is pretty crass.

When you all are finished with Ubuntu's docs, why don't you head on over to Red Hat and mop the floors at night. It's all for Linux, right?

Please.

How about spending the time to just contribute better man pages to Debian. -THAT- is where the community's efforts should go. Not helping Ubuntu-specific wikis.

[yeah, right.]

paid?

I'd argue that nobody does something for nothing. Even "volunteers" are often doing it for better contacts, a sense of well being, or all sorts of things that are valuable to them. That's the main point. Everyone wants to get something valuable for their work, but each person doing the work might have a different definition of what's valuable. Perhaps open source projects need to pay just a little more attention to what kinds of things the people they are trying to attract consider valuable. I'm guessing Ubuntu did no such thing, and documentation, although important, isn't nearly as "sexy" as coding, hence less valuable to many people.

[Peyton]

probably not a problem with open source

More likely a problem with developers trying to do documentation. I know when I wrote software, most of my documentation was shite, even though I was getting paid for it. Coders don't what to document, they want to code. Probably why big companies don't let their programmers anywhere documentation - they bring in tech writers for that.

[Mahou Saru]

Re: Demonstrates the problem with open source

Plenty of commercial products where the documentation is a load of tosh. Some pay for products are even worse coz you invalidate any warranty if you don't get a very expensive "qualified" contractor for even the most basic task. There are plenty of very good "volunteer" based document stores out there.

"people will only reliably commit and work hard when they're getting paid".... boy you ain't worked in the public sector have you!

[foo_bar_baz]

half right

People do contribute and work hard as long as there are rewards. It may not be money, usually it's to improve the product for their own use. Unfortunately documentation is not always the top priority. This is why there is a market for productized OSS-based solutions from firewall software to fully integrated clusters. And experts. If you are not an expert and want instant support you pay a vendor or hire an expert.

[Solomon Grundy]

The Open Source Problem

in this article is the failure of the "community" - not documentation issues. And it does in fact highlight several serious issues with the Open Saucer movement:

1) Everybody wants to be associated with the flashy projects - but when the time comes for the nitty-gritty crap that separates a good product from a bad one everyone bails out. (I would chock this up to the laziness inhernt in every programmer and a lack of compensation for a crappy job)

2) The community is seriously lacking key technical players - as Tanuki said so well above - the community has developers galore, but few of the other technical staff that really make projects work.

3) The community is also fearfully out of touch with the business world. All the hoopla around OSS is fine, but at the end of the day all the "advantages of OSS" are tertiary business issues: not really that important. Almost any product will get the job done and that's all that matters.

Now before I get flamed away for that I'm challenging the community to suck it up and act like professionals. If the OSS community wants true acceptance into the business world they're going to have to learn how to market themselves as more than "freetards" or mega-geeks: they've got to be able to distinctly demonstrate significant business value, diplomatically overcome comparisons to other products, and all that other "management" stuff that techies seem to hate.

Presently the entire community is riding on the backs of a few organizations that have put together a complete team of technical and business professionals. That can't last...

4) A few people above mentioned that code didn't need to be documented if it was written correctly. I refer them to my statement #3.

[Drak]

GNL (GNU's not Linux)

The whole problem are the open source tards who go around trying to get everyone to permanently attach open source with Linux. Linux is NOT just a kernal wrapped inside a "GNU operating system". Linux does not have to be compiled by GNU compilers, nor does it have to use GNU utilitys which are just copys of the the original UNIX utilitys that were designed as part of the UNIX OS. The Richard Stalhlman sock puppets are scaring away all the commericial software companys who think that they will be forced to open source their code (confused with free speech) and give it away for free (confused with free beer). You can make money off Linux, people are not going to leave commerical software wholesale and use the free stuff in open source. Their is money to be made doing commercial Linux, until then, have fun using distros that were coded (and documented) by college kids in their moms basement.

[The Other Steve]

@Mike : almost, but not quite

"1) Good code is self documenting."

Good code _is_ self documenting, not that you see much of it around, but OTOH code of any kind is only a useful sort of documentation for people who can (or want to) read code, and can (or want to) understand the underlying principles (kernel code, for instance, may make little sense to a web developer with no background in OS architecture)

And well written and nicely commented as it may be, the average user doesn't want to download the source package for (say) the 'mount' command and read all of it in order to understand what command line options they need to pass to attach their NAS to their fs tree.

I think you have unintentionally demonstrated one of the limiting factors in FOSS usability, viz thinking in terms of code readability and developers, and forgetting the end users, who don't know, and ought not to have to know, about all this stuff.

[Pheet]

Documentation quality not dependant on Programming methodology

FreeBSD has excelent documentation for example.

The documentation for many closed-source projects is piss poor too (and how well the source code is commented, well, who knows....)

"people will only reliably commit and work hard when they're getting paid"..

What a misanthropic (and inaccurate) world view.

[Brendan Sullivan]

Paid documentation better than F/OSS documentation?

Try using any of the help files in any MS program

Try using any of the help files in any Windows program

Try using the MS "knowledge base"

Try shelling out fistfuls of money for a book on how to use/fix the software your company just paid hundreds/thousands for and trying to find the answer to your problem

Now try using a Linux distro's user guide wiki (Try openSuSE or one of the other 'big' distros for best results)

Try googleing "[distroname] [problem]" or "[distroname] [error message text]" then look at the first few results

Which actually answers your question? Which rarely asks you to empty your wallet just to communicate with a human being who can try to help you? Which one usually bears some resemblance to reality?

[Doug Glass]

All I Want For Christmans ...

... is a "Ubuntu For Dummies" like this:

http://www.dummies.com/WileyCDA/DummiesTitle/Windows-XP-For-Dummies-2nd-Edition.productCd-0764573268.html

Anybody know where I can get a published guide like this? Something close would work, like

http://www.amazon.com/Complete-Idiots-Guide-Windows-XP/dp/0028642325

But I need it to be a regular publication by a known press that can be found at bookstores such as Books A Million, Waldenbooks, Barnes and Noble or etc.

[Anonymous Coward]

Well

I've spent most of my career ensuring that good comments and user documentation gets written in correct proportion to the code. But I'm no longer convinced it's necessary.

The reason I've changed my view is that I'm impressed with what open source has achieved by simply ignoring the user documentation issue. Many users no longer consult manuals even if they exist. They depend instead on an intuitive UI and take clues from the similarity of a new application to others they already know.

If you added a killer new feature to an app, would it be best to describe it fully in the manual, or put a stonking great flashing button on the toolbar to attract attention to it? I know what I'd do. And I wonder how many of the manuals the average Facebook user reads before they start?

So why would Ubuntu need all this user documentation that'll be out of date even before it's finished, given the multitude of independent groups hacking away 24/7? It's far better that it just works the way people expect - out of the box. In an ideal world, documentation wouldn't be necessary. I suspect most developers understand this really, hence the lack of takers for any documentation project.

Of course, if you have a problem, you may need help. But chances are it's an unanticipated problem (otherwise it would be fixed already) so the documentation probably isn't going to help even if it exists. Instead, there's the WWW; always the first and last documentation stop for me. Just Google the error message and either you'll solve the problem or there isn't a solution.

As a caveat I should say I do still think system-level docs are needed. Standards documents are essential, APIs do need describing in gory detail and man pages are a great alternative to reading the code. But for end users of a GUI documentation is increasingly (and should be completely) unnecessary.

[Martin Usher]

What Documentation?

I use Ubuntu daily now and when I get a problem I just hit Google with the relevant terms and up pops a page (or thousand pages) with the solution. That's probably why the documentation effort has got messed up. I'd guess that most of us haven't heard of it and because they haven't had a problem finding information they didn't realize it existed.

The assertion that "you need professional documentation" can only come from someone who's never been at the sharp end. Producing user documentation is a long winded process --- expensive, too -- and it rarely produces anything of value because its always out of date (or just plain inaccurate), it never provides the detail needed for people who know what they're doing and its too detailed for those who don't. It can be done but needs inspired writers,

[Anonymous Coward]

Ubuntu for dummies...

Santa is busy, buy maybe this would do?

http://www.amazon.com/Ubuntu-Linux-Dummies-Computer-Tech/dp/0470125055

[andy]

@Anonymous Coward

Strange posts.

The point is that the wiki is badly organised and has little in terms of minimum standards. It needs cleaning up, but hasn't gained momentum

This has little if anything to do with OSS - the wiki writers don't necessarily write any code. The problem stems from bad implementation/requirments of standards for writing a wiki.

This has no correlation to the quality of Ubuntu, how easy it is to find a 'howto' online (as posted by Martin Usher), or an imaginary lack of commercial support (which is offered by Canconical).

[Rich]

Documentation!

You can't have documentation. Otherwise non-geeks would be able to figure stuff out for themselves and nobody would ever earn a living.

You'll be suggesting 100% UI-based configuration next..

[Anonymous Coward]

Ubuntu Docs blow chunks...

I have been extremely dissatisfied with all things related to Ubuntu over the past year. From 8.04 LTS' suck-ass support for wireless (each successive release is a huge step backwards for usability) to their support forums which I have posted questions and waited weeks with not one single answer. I am currently evaluating a switch to Solaris 10... Ubuntu is crumbling under its own weight. There is only so much that free help is willing to do apparently.

[Adrian Esdaile]

Open source project plan?

1. Set goals

2. Recruit bloggers

3. Collect underpants

4. ........

5. PROFIT!

[Anonymous Coward]

@Good code is self documenting

Another myth.

People can happily write good (however that's defined) code and someone else can come along and think "what the &deity. are all these constants for and what's this function and etc." They then take time trying to work it all out. A few well placed comments can help this process enormously (latest case experienced here being one of the projects that's Use Cased, designed, OO programmed and yet a few comments would help enormously).

[Anonymous Coward]

Documentation

Lets face it, most of these people wouldn't write good documentation, they may be great at programming, but don't see it from the users view. They will presume that you already have done abc, before you do xyz, as it's obvious, well it is isn't it?

The problem with ALL documentation is it needs to be written not by people that write the softwae, but those that use it, but the chances are if you use it, you can't be arsed to document it.

I've only come across one piece of software that is well documented to such an extent that you could set up the system from scratch and run it, without any prior knowledge. But that runs to several thousand pages, broken down into several volumes, bit more than your average wiki.

[Sooty]

Good code *is* self documenting

because its full of comments explaining what it does, if it isn't then it's not good code!

I wouldn't let develoeprs near end user documentation though, that needs to be written by the people who plan the system, the ones who tell the developers how they should build it. This could be written before any code is. Which, i have a suspicion, is where some open source software is lacking.

[elderlybloke]

Dear Drak

Are you trying to be rude or does it just happen naturally for you?

[KarlTh]

Hmmm....

Dictionary definition of Linux documentation in general:

Recursion: See "Recursion".

[Dennis Healey]

Missing the point

Most of these comments seem to me to miss the point. The first thing to remember is that we are for the most part techies and therefore are a) in the minority and b) have a very biased view point.

All the talk here has been about documenting code. This is all very interesting for the programmers, and good code may (or may not) be self documenting, but what about the other things.

System architecture - needs to be documented as it is not obvious from the code.

User documentation - is crucial and really needs to be designed to be easy to follow and easy to find the relevant bits.

Speaking as a new user of Ubuntu and Linux who considers himself somewhat more techy than "normal computer users" (note not normal Linux users). I have installed the system & get on fine after a bit of exploration with the GUI and can do 95% of what I need to do. However when it comes to the last bit, when I need to do something a little bit more complected, to scratch under the surface it rapidly becomes much more hostile.

An example - I have downloaded several programs using the GUI and all have downloaded silkily and installed as smoothly. I then downloaded an anti-virus program which didn't. It needed access to the Root user and didn't seem to work with the graphical process. As it happens I know what root is and understand something about it (not the position for everyone). However at Install no root password was defined by me nor was I given a default. All the help I have found doesn't help.... it uses programs like SUDO ?!?! WTF

The point is - not my own problem - I'll solve that sooner or later. The point is - I shouldn't have to, and if there is no intuitively obvious solution (and the GUI makes a reasonable job of being intuitively obvious for many things) I should be able to find help, in a form I can readily understand, and it should be readily accessible. This I concede is difficult and the job of a talented Educator/technical writer but is VITAL if this is to become mainstream.

In the MS world it feels like I can take the slope down the hill of complexity to the valley of the programmers caves. sometimes its steep and sometimes not, but it is a slope.

In the Linux world I can walk about in the lush pastures with the butterfly's and the skylark or I can walk over the cliff edge.

. . . maybe I need a microlight!

Paris cos even she read a book about IT once.

[Anonymous Coward]

Documentation is excellent

let's keep it 'poor' in the eyes of the masses :)

Personally I think the docs are perfect - great man system - info is there as well.

I can even view man pages in the editor with a quick :Man man Ctrl-W L :Man man .

I really don't know what the fuss is all about - oh that is right not only can the Ubuntu lot not read man pages, they are too cheap to buy a decent book as well on the whole.

Might I offer the suggestion of the Purple book, the Green Book, or Essential System Administration by O'Reilly, or and here is an idea you pay for support from Ubuntu so they can pay people to write docs.

Oh opensoure is lacking architects is it :) Yeah right, everyone wants to specify, not many can do.

The building industry analogy is fundamentally flawed, because the one with the skills and the overall vision are the developers, they are the architects and the funders.

The brick layers are the help desk and 'admin' if you will, along with project manager wannabes, and boy do we have a lot of project manager wannabes not capable of coding but capable of whining. It is easy to be a critic, but try cutting some code and developing a solution then you will see just how ignorant you actually are :) And really brick layers are not required, we have our buildings without them, it is a digital world, where you get an idea and make it a reality.

Most of the software I use is excellently designed, and vritually all has been done by a developer, no project managers insight. The architecture is wonderous, and the design is fully customizable, to whatever works well for me.

The problem as always, is Ubuntu attracts the windows users, it is the Ellis island if you will of the Linux world. And life is tough there, what with bad advice, and windows habits to overcome, but hey if you want to be using Linux and you don't want to pay for professional support you have two options:

The freetard route, which is amusing, and be prepared to have people tell you how to ask questions correctly, or who try and get you to 'volunteer', yes you too can give yourself the illusion of giving back by writing naff docs.

Or, you suck it up and read the fine manuals and buy some books

Developer caves; right you are going the wrong way, we are all up in the clouds in our little castles of technology. Down in the caves are the 'Windows Power Ranger Users' trolling away. Developers are upstream, not downstream.

And frankly why do users think developers care about them. Developers care about their code, and wealth. Just like everyone else, they are not your servants, and they don't really give two hoots about your experience, unless you are offering some wonga.

See users in Linux are developers, there are no free loading users required. The 'volunteers' are ex windows users who cannot code, they think they are giving back but they are not, they are just encouraging more windows refugees.

If you are not a professional then hire one, they come at market rates, and only adjust charge according to how much of prick you are with your analogies.

[The Other Steve]

@AC (naturally)

"And frankly why do users think developers care about them. Developers care about their code, and wealth. Just like everyone else, they are not your servants, and they don't really give two hoots about your experience, unless you are offering some wonga."

Thanks for summing up the FOSS philosophy so well, I tried to hint at it, but ICBA with the flamage, nice to see a died in the wool freetard admit the truth for a change.

Presumably, you are not one of these "Linux on the desktop to replace windows" morons then, since obviously that view and the one you have just espoused are diametrically opposed to each other.

Other stuff :

"boy do we have a lot of project manager wannabes not capable of coding but capable of whining. "

The ability to write code is not essential for a project management specialist, (big hint in the name) OTOH a certain subset of PM skills are essential for any developer that has to work to a schedule, or with others. Lots and lots of developers fail at this. Usually the really arrogant ones who think they know everything.

"It is easy to be a critic, but try cutting some code and developing a solution then you will see just how ignorant you actually are."

If only that were true. Plenty of arrogant fucktards out there who have dived into coding, turned out FOSS projects that are truly ugly, badly written, and hard to maintain or improve, and yet haven't, in fact, realised their ignorance.

I've seen plenty of release code that looks the kind of scratch code I write in the first hour of tinkering with a new language or API, clearly constructed with no clue about coupling or cohesion issues, functional separation, or any kind of quality considerations at all. Software engineering, pah. They've heard of it. Probably from reading Slashdot.

I've found spaghetti messes of procedural code wrapped in Myclass::SomeFunc() tinsel that doesn't warrant the overhead of object instantiation. I've seen brain achingly complicated compound logic operations stuffed onto one line, wrapped around with so many brackets it boggles the mind, and yet still relying on implicit operator precedence _at the same time_ that were clearly coded by trial and error, take hours to factor out, and usually reveal poor original assumptions about the architecture of their containing code unit. Functions and class methods that run to multiple thousands of lines...

In short, all of the ways to write shit code I have found in FOSS software of various types. People with exactly your sort of attitude cut themselves some code, think to themselves "It works, I fucking rock" and ship it, thinking how fucking clever they are. Who cares if it crashes ? Fucking whining users, after all this stuff wasn't written for them, it wasn't created to fill a need, it was written in order to boost the author's ego, it was, essentially, just an extremely contrived form of wanking.

Professional developers don't get to behave this way*, but then as you rightly point out, FOSS developers don't have the same responsibilities to consider. Fortunately for everyone concerned, many actual FOSS developers take a more caring attitude to the people who will have to use the code they grunt out.

But thanks for being such a good example of exactly why FOSS based operating systems still lack, and will continue to lack, both market and mind share. And also why plenty of seriously experienced and talented techies are walking away from FOSS in disgust.

BTW I notice you were very careful not use the word "we" in your deification of developers ...

*I did say "professional", _un_professional developers act like this all the time.