RANT - Bad documentations
 

Anybody else sick of bad documentations online? You know what I'm talking about. You need information on how to get a program to work, or a server running, so you go online and read their online documentation only to find out that it's not n00b friendly. In fact, it doesn't even make sense. It's like they always throw you out in the ocean rather than showing you the basics of swimming, if you get my drift. Whatever happened to the 1-2-3's of how to do something, kind of like those "For Dummie" books. I find those are really easy to understand and getting started. I just wish online documentations could be like that. I can now see why companies hire professional documentation writers.

Well, a lot of developers spend their time writing code, not documentation. I'm all for documentation, and being a pseudo-developer, maybe I should find a position in some project to do documentation. Maybe even on Gentoo linux, it's a thought. (Consider this an open offer to any project).

Re: RANT - Bad documentations
 

exactly - writing about something you know perfectly, in a way that a total noob can understand, is actually a very difficult thing to do.

The worst part is, when asking questions or if there is a HowTo online, some developers come back "Well why don't you try writing the documentation?"


Um, in order to write a HowTo, you need to know how the package works. Hullo, logic please?

Others, well, they try to make the time writing documentation but instead spend time building stable packages, and spend the rest of their time answering questions on mailing lists and boards - but that time on the boards may be better-spent in getting the documentation done, writing a quick FAQ, then 90% of the time normally spent on boards and mailing lists is now eliminated.

See, part of the problem is this: because many open source development projects are done as a hobby, or a "second job" if you will, often a professional approach is not taken. Conventional development process goes out the door - requirements and functional specs won't get written before diving into the code - *maybe* a quick design spec is written, but it's primarily to establish a solid or at least good architecture and to define coding styles. In a professional software development environment, requirements DIRECTLY feed a functional spec, and a functional spec can be turned into a user manual or HowTo targeted toward technical users in a matter of minutes to hours. Because there is no requirements document and no functional spec - or at least not a proper formal one, the normal basis for a user manual is nonexistent - so now there may be an outstanding enterprise-quality free open source application to perform functions X, Y, and Z really well, but because there is no documentation, no one knows how to use it, and people have problems with it becaue they're mis-using it or they simply don't know how to get it running or what the system requirements are (unless they are fortunate enough to obtain RPMs).

There's my $02. It's a catch-22 situation and EASILY resolved if planned properly from the beginning. THe functional spec doesn't have to be a novel, or a 30,000 page whitepaper resembling Intel's Pentium documents, but it should be at minimum a detailed outline.

try using BSD they have exelent online documentation and i think its pretty easy to understand.

but you cant beet the good old manual you used to get with a computer i remember our first PC came with a manual that was over 5inch thick and our old spectrum i still have the manual for someware pitty i didnt have the spectrum itself coz i cant remember it ever crashing

Is anyone reading this thread old enough to remember the 200-page manuals that came with the Commodore computers that covered every single command you can run or code into a BASIC program, or the DOS 3.3 and earlier manuals that came in three to five THICK binders and covered DOS operation, batch files, maintenance, etc. in excruciating detail? THAT was documentation.

Even Commodore, the slackers of the computer industry once they became king, continued to produce excellent documentation for all of their products right up to the end. If you bought an Amiga, you didn't need anything else to learn to code - you received an AmigaBasic manual with your computer. That is excellent.

Today - documentation? Yeah. Right. Even which is considered by today standards to be good documentation STINKS in comparison to what you used to get with a product - be it a computer, a word processor application, or a development environment.

I remember coding assembly on the Commodore 64 and 128 - and with the assembler I received sample assembly code, sample machine code, hex editors, ASCII source editors, detailed documentation on every single command and operator, and a map of every single register for each operating mode of the computer. Using the documentation which came with the assembler, I managed to actually get BOTH processors (the Z80 and the 8510) to process code simultaneously on my Commodore 128. Excellent documentation.

Even today's Microsoft Visual Studio, the current Holy Grail of development environments, pales in comparison to what used to be considered good documentation.

Well I'd agree with Micro420,

I'm no techie, I use linux for ethical reasons i.e. I don't like the parasitic business practices of M$.

It means that I've had to learn lots of stuff that I don't really want to, but to get where I need to be etc etc.

Yes, theres the excellent linux documentation project, but that seems to be flawed IMO because they just seem to put docs into a common location and in a common format, but not a common and easily understood language.

It is partly the fault of the developers, because most of them are genuinely working/developing at a considerably higher level than most of us mere mortals, and as such they will naturally forget that theres considerable knowledge that they "just know", but which requires "us" to have to learn considerable amounts of "prior knowledge".

Theres also a few sites that offer guidance about what a few of the plethora of commands actually do, but otherwise "we're" restricted to the bloody awful use of English that is "man pages" (a guide to which is in my sig, but even then it's not as helpful as it could be).

I'd prefer things in "plain English", because that way, it should (theoretically) be straight forward for translation software to mod it into other languages, for the benefit of all.

Then again, English lang and lit studies aren't usually that high on their list of priorities.

It's laudable that "they" write documentation at all, though it's fair to say that if "they" didn't, then the whole linux world would probably much more "niche".

It's not as if you can complain about the slightly differing ways that language is used between the continents, because apart from different (slightly more phonetic) spelling used in the US/Canada to the UK, and occasional difference in emphasis between the UK, US/Canada and Aus/NZ/South Africa theres little or no difference in how "plain English" actually comes across. After all, say for example, you read those curious little magazine things handed out by the Jehovah's Witnesses (I had a friend who "converted"), you can't but help to know that those are aimed primarily at middle class America (which is where I understand that "it" all started).

As for Matirs offer, well gentoo isn't a good example really, because again IMO their basic installation handbook and the desktop setup guide is some of the best out there i.e. even an idiot like me managed to do a stage 3 + GRP install, then get both KDE and gnome set up and working with the nvidia driver. Though there does seem to be some "room for improvement" in the more subject specific docs at the gentoo project.

Yes it would be great if there was some linux enthusiast technical writers and proof readers (with a smattering of novice installer/user types who know which is the "right" question to ask) to produce some clarity and conformity in linux documentation, however unlikely.

As to whether it's a big job to produce docs like that, even if they're only available online, say as pdf's or something? Well, I suspect it is. Which is why places like LQ are such valuable resources.

regards

John