Slashdot Mirror
Ask Slashdot: What To Do About the Sorry State of FOSS Documentation?
First time accepted submitter TWX writes I've been out of computers as a serious home-hobby for many years and in returning I'm aghast at the state of documentation for Open Source projects. The software itself has changed significantly in the last decade, but the documentation has failed to keep pace; most of what I'm finding applies to versions long since passed or were the exact same documents from when I dropped-out of hobbyist computing years ago. Take Lightdm on Ubuntu 14.04 for example- its entire configuration file structure has been revamped, but none of the documentation for more specialized or advanced uses of Lightdm in previous versions of Ubuntu has been updated for this latest release. It's actually harder now to configure some features than it was a decade ago. TLDP is close to a decade out-of-date, fragmentation between distributions has grown to the point that answers from one distro won't readily apply to another, and web forums for even specific projects are full of questions without answers, or those that head off into completely unrelated discussion, or with snarky, "it's in the documentation, stupid!" responses. Where do you go for your FOSS documentation and self-help?
The one thing Linux really, really lacks, compared to the *BSDs is the quality of the documentation. Not even Google makes up for the deficiency.
learn how to use a program by reading the source code!
I jest, of course. It's not just open source projects that have this problem, though; plenty of commercial applications also have shit for documentation. The upside in open source being that you *can* read the source and build documentation from it, if you were so inclined.
Writhe your naked ass to the mindless groove.
Hire someone who knows the product (a starving developer?) to help you.
That is completely unreasonable. If I have to read the source code just to be able to understand how to use the program, I will just wind up using proprietary software with proper documentation.
I've never seen JavaDocs that add anything to the source. It's okay if you need a list of methods or parameters, but usage is lacking.
Documentation needs to have several *working* examples (not snippets) from a simple Hello World to more sophisticated but still commonly used. A single example that illustrates every imaginable feature and use case is rarely helpful.
I document my findings on the Ubuntu wiki. If more people would take the hour to write up details on what they spent 2 weeks learning, we would all be better off for it.
The problem is most software is complex, and documentation is an attempt to simplify the work flow. But the documentation if complete would probably be just as large if not larger then the code, and just as complex to read.
What I find for good documentation is down in the FAQ, or a quick spot where you know a particular area is kinda clunky in the UI, or just a list of of the features you can use and what they do. Not a formal write up in a 1000 page book. But the appendix, and the list of tables is usually enough.
If something is so important that you feel the need to post it on the internet... It probably isn't that important.
In the past, there was usually a fairly good set of manual pages that seemed to accompany most OSS projects. However, nowdays all huge portion of projects seem to just think that if they set up a documenation wiki, they don't need to do anything else and some awesome documentation will just appear.
I am saddened to say that the lack of proper, structured documentation, combined with bad experience every time I asked a question on OFSS forums kept me away from OFSS in general (and Linux, more specifically). Every year I try again and I am seeing the same results.
I know I might ask questions perceived as "stupid" but everyone's been a newbie at some point in time. Maybe it's just my turn to be one. Thing is, once I get the correct, detailed answer I never ask the same question again but I almost never get the answer, just "RTFM" and "haha noob" with the obligatory variations.
Of course, I've been trying to ask very specific questions, I've provided detailed information on my issue and was very polite myself. Still was met with smug and bile.
In all fairness, creating documentation is something that almost nobody wants to do. I get that. However, politely answering a question shouldn't be that difficult.
...gis sdrawkcab (usually not responding to ACs; don't bother posting as AC)
If the webpage for your application consists entirely of a long list of bug fixes, you're dong it wrong. This is why you need more than a programmer to make a real application. A technical writer and even a [GASP] actual UI designer can take you from amateur hour to prime time.
SJW's don't eliminate discrimination. They just expropriate it for themselves.
That is indeed why proprietary software is almost always kinder to a developer, yes. You see if you don't maintain the documentation developers won't like it and if developers don't like it you won't make any money from it. Profit motivates good practice in this area.
God I wish I had a million mod points for you.
SJW's don't eliminate discrimination. They just expropriate it for themselves.
That sort of attitude is the problem.
Building the application and writing the code is half of the project. The other half is documenting it. Yes, you'll spend twice as much on the project, but that's counterbalanced by someone else picking up and improving it a lot faster.
Also, undocumented code is a half-assed job, no matter how well it performs.
...gis sdrawkcab (usually not responding to ACs; don't bother posting as AC)
A huge amount of documentation for various projects like GNU groff, GNU nano, Vim, and others, have implicit assumptions that users are familiar with those tools' traditional Unix counterparts. 'man nano' for example, doesn't describe any of the keybindings for the editor, instead assuming that users already know pico. The groff documentation in places explicitly states that it only documents the difference between groff and Unix troff.
Linux has won. Most Linux users have never used a traditional Unix, and most never will.
...but it's being eaten...by some...Linux or something...
Some years back I decided to play around with FVWM. I was astounded with quality the man pages. FVWM isn't so much a window manager as it is a window manager *kit*, with lots & lots of configuration options. But the documentation is some of the best I've seen.
I've just been trying to work with lightdm here, myself (disable guest login & not auto-fill-in the last user name) and found the same as you. The config files have even been moved and no-one bothered to mention that.
Anyway, I usually end up in some user forum or other. Luckily I haven't had many unique problems. Almost always someone, somewhere, has had to figure it out before me & is willing to pass on the info.
That pretty much sums it up, sans all the foul words.
...gis sdrawkcab (usually not responding to ACs; don't bother posting as AC)
Wow...
Reading the source isn't documentation.
You can see what it is doing, but you don't know why is it doing it, or what it is trying to accomplish.
Much like the idea if it is Open Source then it is also Open Specification. Which isn't true.
The source is the instructions for the computer to follow, the documentation and specifications are for the people to know what the product suppose to do.
Often software will have a glitch, it doesn't get fixed, because there is not documentation or specification to compare it against. So the bug either gets worked around or just ignored while the program is still faulty.
If something is so important that you feel the need to post it on the internet... It probably isn't that important.
I bet most projects would be happy to accept patches to their man pages, and files they store in /usr/doc/ if they improve quality or accuracy.
This is one of the few areas where just about anyone can contribute even if you don't code. Chances are you can still read it enough glean what the expected options are etc.
Repeal the 17th Amendment TODAY! Also Please Read http://www.gnu.org/philosophy/right-to-read.html
The wiki for Archlinux is pretty much the best source of information on the web for linux, as far as I'm concerned. It's valuable even if you're not running Archlinux, with detailed guides for configuration of many FOSS programs.
I have found https://wiki.archlinux.org/, the Arch Linux Wiki to be the most useful single source of information taht is generalized enough to apply to most other distributions.
As an early adopter of Linux, I too found the existing documentation appalling and started writing better documentation, which led to co-authoring RedHat/Fedora Unleashed with Bill Ball.
My advice is to contribute to the documentation yourself since it appears that no one else, including the software authors, care much about it.
But the barriers to contributing are high. You may not only need to learn about the application, but you need to learn any number of arcane editing and versioning tools, and then convince someone in authority to accept and include your changes. It's really no different that contributing code to a project and for your average writer, that's a huge hassle and likely a big part of why more writers don;t contribute.
"I believe in Karma. That means I can do bad things to people all day long and I assume they deserve it." : Dogbert
I like Javadoc (or Doxygen, which I use often), but read the source is horrible advice. Source code can be anywhere from elegant and clear to $DIETY awful spaghetti. Source code tells you precisely what the code does, not what it was meant to do (sometimes those differ and we call them bugs) or why it was done that way.
Ask Slashdot: What To Do About the Sorry State of All Software Documentation Everywhere?
I find being offended by me offensive.
For YEARS there's a been a file named INSTALL_SOURCE or something like it. Indeed, there's a section on that, but a lot of the file is how to download and install precompiled binaries. It's a little thing, but it just bugs me ever time I have to skip past the stuff that shouldn't be in there to get the stuff that should.
For a product intended for use by non-techies, LibreOffice's end user documentation is horrible. It's uneven in coverage, lacks useful examples, and is generally not sufficiently detailed. Comparing MS Office's documentation to LIbreOffice's documentation should make this obvious to all involved in LibreOffice even if they, themselves, are not "non-techie end users" and think "just read the code" is a good answer. This lacking reduces the uptake of LibreOffice unfortunately.
Interestingly, the fact that MS Office code is not open forces MS to document its use well (although they probably would have anyway as MS does understand that a product is not just what the compiler spits out) - even if just so third party "self help" books can be reliably accurate.
Why is there an "insightful" mod and why isn't it "-1"? If I wanted insight, I wouldn't be reading
You think it was bad then? Well, I'm not saying that it wasn't, but it has gotten a whole lot worse lately.
The neckbeards you speak of are now in their 50s and 60s. A lot of them have, I'm afraid to say, died. They didn't live the healthiest lives when young, and they have perished because of this. A lot of the others have been marginalized as we've seen the hipster tide sweep in.
At least the neckbeards had real experience. Most of them had gone to college, and a lot of them had graduate degrees and decades of industry experience. They may have been assholes at times, but at least they were competent. They wrote good code, even if they didn't always provide documentation.
The hipsters have none of this. Most of them are in their early 20s, if not younger. They have no real education. Their knowledge is extremely limited, but they don't realize this. This is why they think JS is a good programming language, for example. They have absolutely no idea about anything else. The software they write is typically total crap, and documentation is completely foreign to them.
At least the neckbeards could be depended upon to provide useful information about how their software worked. Maybe it'd take some fighting with them, but eventually the information would come out, and it would be correct. It's a different ballgame with hipsters. They don't know how the software works, even when they wrote it. When they claim to know how it works, they actually don't. So if you're trying to write documentation for their code, not only do you have to deal with shitty code (assuming you know how to), but you can't even rely on the developers themselves to know how it works, how to use it, or what it's even supposed to do.
As somebody who has contributed documentation for several neckbeard-run projects and several hipster-run projects, I would be more than happy to deal with the neckbeards any day. It isn't a good experience, but it isn't a total clusterfuck like it is when dealing with hipsters.
"If you can't figure out how to use the program then how can you write documentation?"
Yes, exactly this. This is the exact location of the issue. The coder cannot write documentation, because he lacks empathy for the people who are using his program. He knows this, which is why he asks for help in documentation. The help arrives, but he lacks empathy for the documentation people equally. A little introspection by a developer goes a long way towards solving this problem. However coding in Mom's Basement (tm) doesn't lead one to that kind of response.
Agent K: A *person* is smart. People are dumb, stupid, panicky animals, and you know it.
I would have to agree that most javadoc doesn't add anything to the source, but it does pick out the stuff I'm interested in (api) and hide the stuff I'm not (implementation). At least, when it's actually filled in with minimal descriptions (all too rare).
This is silly. I've been trying to use Autodesk Fusion 360 - it's most definitely a proprietary bit of software from a large developer.
The documentation is worse than awful; you'd be better off just reading the source.
And iOS vs Android? iOS is pain layered on suffering. Reading the source would be _so_ much better than depending on Apple.
Commercial != good doc.
"Incomplete Documentation
Open Source nerds don't have the discipline to write documentation because it's no fun. Writing new code is fun. Fixing bugs in old code is less fun. Writing documentation sucks. Which is why most open source software is buggy and features little to no documentation making it useless to everyone outside of the authors".
http://www.grumpynerd.com/?p=1...
"Kill 'em all and let Root sort 'em out"
How is this problem specific to open source? Some F/OSS docs are great, some not so great. Some communities are really helpful, some not so much. But how is that any different than the situation with proprietary software?
I disagree. Without the foul words only half the story would be told.
While emoticons fill a certain spot when it comes to conveying emotions in written texts they are extremely lacking in the area that foul words cover.
Or to sum it up, all words enriches the language. Even intentional misspellings diversify the language. The distinction between a moron and a moran is sometimes interesting to make.
How about crowdfunding some documentation efforts by real technical writers?
The reality, for better or worse, is that writing FLOSS code has sufficient apparent benefits for the software engineers and their sponsors to get the job done. The technical writing of good documentation does not. Whatever the reasons, it is the case; that has been the reality for decades.
But how much would it cost for a first pass at documentation? Take "Installing and Configuring MyCloud" as the example. Contact a few people who have written articles or put up YouTube videos on the subject. Let's get a high estimate; call it $100/hr, one month, three documenters, 10 hours per week each, 50% overhead = $100 * 1 * 3 * (4 * 10) * 1.5 = $18,000.
That seems do-able, and a good opportunity to develop a crowdfunded brand; a team that grows a reputation for getting projects done. Then you could offer a follow-on project to do a deeper dive on the same subject, or put together another team to do Asterisk & Secure VoIP, or whatever is next. Maybe start with the counter-NSA stuff, where there's a sudden broad interest and complex software that, until now, has been run mostly by experts.
A few thousands of people willing to kick in a small amount of money each toward a common goal; crowdfunding documentation seems like a natural fit.
Stop-Prism.org: Opt Out of Surveillance
The state of FOSS documentation is about the same or, in my experience, a bit better, than the state of software documentation in general.
Because they include documentation as one of their priorities.
I find FreeBSD typically has far better documentation than the various patchwork Linux distros. A lot of FOSS projects are actually quite well documented.
The biggest problem with documentation is developers don't want to help maintain because it gets in the way of keeping their projects in a perpetual beta release state by changing things constantly.
Stable and mature software that can be properly documented = stale software that's less interesting to developers.
he means in-line documentation: /*
Function: Compare
Compares two Types
Parameters:
l - lhs
Returns:
boolean result
*/
Etc... as opposed to external documentation.
It's rare that someone would leave inaccurate documentation inline with the code.
Ok, yea, we've all done it on our local machines... but to them publish that?!?
But I think you need both. External documentation is more for theory and meathodology. "This program is designed to do X and it's command line only because of Y" Etc...
In-line documentation is more for "I used a string here because sometimes this numerical value does Z" etc...
You need to document both the forest and the trees.
Wait, wait. We're talking about different things here.
In a dev house, as you call it, there's going to be different people with different jobs. The developer writes code and comments it, then there's a content writer who does the documentation. Also these tend to be for-profit organizations which don't do much OFSS (if any at all).
...gis sdrawkcab (usually not responding to ACs; don't bother posting as AC)
Perhaps new contributors should start with the documentation, then "move up" to contributing code? Or would one more barrier to becoming a contributor merely make things worse?
Nah, without the foul words, it wouldn't be accurate. Most are motherfuckers (i.e., their mothers are the only person that would find them lovable enough to fuck).
That is all.
fix it yourself.
How the hell is someone supposed to DOCUMENT something that they're trying to figure out how to make work?
Are you a black hole of utter cluelessness?
No clue will ever escape your infinite singularity of utter incomprehension?
Once a clue passes your event horizon it's never seen again?
Do you emit Hawking Clue Radiation?
True, but it might antagonize other posters. :)
Rarely would a constructive discussion stem from that kind of foul-word-peppered root
...gis sdrawkcab (usually not responding to ACs; don't bother posting as AC)
What was nice about MAN pages is they evolved iteratively very much like Wikipedia. Wikis for open source software might be a modern version that works.
Do any F/OSS projects allow you to report bugs in the documentation using the bug reporting tool?
MOTHERFUCKER, IT DOESN'T WORK LIKE THAT. Fuck you in your goddamn asshole you fucking arrogant fucking pricks.
Your documentation must have been epic.
const int one = 65536; (Silvermoon, Texture.cs)
SJW, n: "Someone I don't like, and by the way I'm a fuckwit" - AC
Programmers acted like arrogant jerks? I don't believe it!
On Debian, this is the directory which contains documentation outside of the man/info directories. Sometimes to get documentation for a package named foo, you have to install separately the package foo-doc. Debian does this to separate free software from documentation which does not satisfy its own guidelines for free software.
I don't know why that comment is at -1. It perfectly describes all of my experiences with GitHub-hosted stuff, too. I have to use a lot of JavaScript libraries at work, and many of them are hosted at GitHub. Like the parent comment says, there's usually no documentation, not even README files. I don't know if it's due to incompetence, or inexperience, or just because they don't care, but documentation of any sort is very rare when it comes to GitHub-hosted projects. Even if a GitHub-hosted project does have some documentation, it's usually outdated and incorrect, or it's in a wiki where most of it is just "TODO" or "fill this in" placeholders. The only JavaScript projects with usable documentation are the ones that are primarily hosted elsewhere. I wince whenever I see that a library is hosted at GitHub. It means I'll have to struggle a lot to figure out how to use it because I'm pretty much guaranteed that the documentation will be awful, if there even is any.
I will just wind up using proprietary software with proper documentation.
Same here.
I love the idea of Open Source, community-driven projects, and I'm happy when they provide useful software to people for no cost, and I'm happy that there are people providing competition for the big name software companies.
I'm also a busy person. If I've got work to do or something important to finish personally, then realistically the cost of buying more polished commercial/proprietary software can often be justified instantly.
That might be because it has comprehensive documentation, but much the same applies to the usual FOSS weaknesses: ease of use, or compatibility with industry standards, convenient availability of professional consultancy and training, and so on.
(Of course, I am similarly sceptical about proprietary commercial software where the documentation or ease of use don't justify the high prices sometimes asked. This isn't about FOSS, it's about whether it's worth spending real money to get a much more practically useful product.)
If you disagree, post your argument. (-1, Overrated) isn't your personal censorship tool for views you don't like.
I'm a rather odd duck. I did a lot of coding in college and my first job (writing software for hospitals) but have since moved to system administration/design and have a degree in technical documentation. I've written books on Linux and have documentation up on the LDP, some of which is still in use. So I've seen all the sides.
Coders are too busy writing code and making changes to what they write to give time for accurate documentation to be written. The days of "read the code for documentation" are long gone when you have multiple layers of libraries and applications to go through to find what you're looking for. This kinda worked in the days when you could fit an entire Linux install on three floppies but now that you need a few GB there's no way a single human can keep track of it all. Documentation takes time to write and get right. In the age of using github as a distribution and code changes between today and tomorrow, the documentation is suddenly invalid before it's written. Even then, it requires a lot of stupid questions asked by the documentation staff to coders who think they have better things to do.
As for TLDP there was a bunch of problems. Using DocBook was brilliant, but the toolsets were terrible to work with and difficult for people who never used SGML or XML. Linuxdoc was easier to use but really wasn't the way to go long term, especially since the tools were Linux-only and meant the tools were of limited use. Once Wikis took over online there wasn't enough enthusiasm in TLDP to convert and lead the charge.
This. This guy gets it. And it gets really old having programmers blame all of their issues on "I gots the aspergers" and "I'm a creative person". The source code for most FOSS projects is a terrible mess anyways. People just shove their hands in wherever they want and leave garbage behind. Good source code seems to only come from individual / small team (<5 devs) projects and some commercial software. A few older semi-FOSS projects (more the freeware not OSS or shareware projects) for Windows aren't too bad either, but the programmers all eventually let the projects go as they are highly employable and get jobs that pay them for their quality work.
The GNU and Linux communities are rife with people who aren't otherwise employable and can't keep it together personally or professionally. I don't mind deploying Linux servers for specialized purposes, but you can be sure I disable automatic update mechanisms most of the time to prevent the inevitable critical application breakage that the lack of testing and consistency brings.
I write code as a hobby and *gasp* I thoroughly document it, and in all fairness I don't do it for my customers (I have none) but for myself. I realized, couple decades ago, that if I don't comment my code it's a lot more difficult for me to remember what I did months or years later.
...gis sdrawkcab (usually not responding to ACs; don't bother posting as AC)
Where do you go for your FOSS documentation and self-help?
Documenting code is different than documenting an interface. As an end user I honestly I don't bother with FOSS documentation for the most part because it's generally so bad. (Sadly non-FOSS software is too seldom much better even when it should be) While there are times when I have to dig into whatever is available, I generally don't bother with any application (FOSS or not) that I need to consult the documentation to figure out unless I absolutely have no alternative. It's sort of a quick and dirty way of sorting out what I want to use since 99% of what I do does not require deep magic. If I have to get out the manual then chances are that the application is poorly designed and will most likely cost me more time than some alternative. There are exceptions of course but it's not a bad first pass filter.
As a random example it's why I can't be bothered with EMACS despite the fact that it's an absurdly capable piece of software. (I don't like vi either so spare everyone the holy war) If I have to consult a manual to do even the most basic things in the application then it isn't worth my time. (Ctrl-x Ctrl-c to quit? Seriously?!? No thanks) I don't want to memorize a random list of key shortcuts especially for an application I'm just starting to use. Installation routines should take care of all but the most arcane issues. Applications should never require magic keystroke combinations or buried options for common tasks. Minimalism is fine but not when it hides so much that I can't immediately discern how to do a task (I'm looking at you Apple). If I need a tooltip to figure out what something does then it is badly designed. If I have to pull up a help screen (press F1 etc) then it is really badly designed. If I have to look at a man page or consult a third party reference then it is probably completely broken.
I think good documentation is important but it should never be a substitute for a well designed interface. Furthermore documentation for users (code is different) should primarily serve two purposes. 1) To get people up to speed on basic tasks with an unfamiliar application and 2) To document weird corner cases and how to deal with them. 99% of what any application does should not require special documentation. If it does then it needs to fixed until it is in a state where it no longer needs the documentation.
Further proof that what I'm saying makes sense. Thank you.
...gis sdrawkcab (usually not responding to ACs; don't bother posting as AC)
There is no glamor in writing documentation. You do not get any kudos for writing documentation. You only get kudos for writing good source code. No one makes you the keynote speaker at the hacker convention because you write good documentation. Maybe if they paid people to write documentation?
When I worked in a software company, the first people to be laid off were the people who wrote documentation.
I used to buy books for Linux, but it was a waste of money and time to buy and read them. By the time a book would come out for Linux, they would have replaced how the user interface worked or rewrote the tool.
This exact story could have been posted the first day I visited /. and nothing has changed nor will it change. Keeping the documentation up to date with good examples is boring work and few want to do it. A lot of open source developers do it for their own benefit and will simply say that's not their problem. Since most of it is a volunteer effort you can't make them do anything and the few who want to write documentation can't make a dent in the number of changes that should have been documented.
There are of course exceptions but they usually intersect with the kind of software that runs business critical applications where a lot of time and money is riding on it and paid developers do a lot of the work. Or you have someone who's being a bit of a nazi on it, but they tend to often get overrun by a fork that's moving more quick and dirty. Because users like to complain about poor documentation but they want the shiny new features too and there's not a few forks that's started because someone was rightly denied commit privileges.
Personally I got tired of waiting for the gold at the end of the rainbow when things would finally stabilize and get working and documented and done. It is a half-baked work in progress and if you got the time and interest to deal with it please do. I managed to make Linux work for me for about 3.5 years, thinking I'd eventually get to stop tinkering with it but despite releases coming and going fixing some issues new ones appeared and it never really settled down. I finally decided to get a Win7 license four years ago, I guess Linux is an escape option if Microsoft doesn't clue in from Win8/8.1 but I don't expect much has changed.
P.S. That's something I heard often, you tried like a 12 month old distro? Try it now, all your criticism is outdated and it's totally different and much better now. I used it long enough to know that's usually total BS.
Live today, because you never know what tomorrow brings
Eeh. I agree that, as a user, it's frustrating when software doesn't have proper documentation.
On the other hand, if someone donates his time to develop a program and makes it free software, it seems hardly fair to fault him for not writing documentation to go along with it.
Someone who really cares could, of course, do it themselves, or offer to pay the developer to do it. If most people don't care enough to do that, then maybe that's the problem to focus on.
If someone comes along and gives you a free hamburger, you don't complain that they didn't bring fries and a drink.
Comment removed based on user account deletion
To blow my own tiny trumpet for a moment, I've written and updated a manual to go with: http://sourceforge.net/project... for each release.
However, it isn't terrific AND I worked as a technical author for a number of years, doing mainframe software manuals. This is my main point, good manuals [mine is not] are hard and probably require equivalent effort to the software itself. The other big obstacle is that in, for example, mainframe world there is formal review process, formalised customer feedback, errata etc. etc. Also, manuals are planned as a 'set' installation, operation, troubleshooting, API etc.
I don't know a lot of my customers and can only correct things that appear in the Google group. In my case, since it's a niche. there's not very much.
Actually there's an opportunity here as well, in that non-code people could also participate in their favourite projects by writing guides. Indeed sometimes they do, but not often enough and they're fragmentary.
On y va, qui mal y pense!
You must have missed OpenBSD, then.
I know, I know: It's an exception. I just wanted to mention the best documented Free Software I've ever seen.
Knowledge is power; knowledge shared is power lost.
That is completely unreasonable. If I have to read the source code just to be able to understand how to use the program, I will just wind up using proprietary software with proper documentation.
On the other hand, I've noticed a steady decline in documentation for commercial software too. Manuals have gone from the thick reference books I remember from 20 years ago to little "quick start" books if you're lucky. More frequently no documentation at all.
Self documentation is going downhill too - there seems to be a trend to removing UI hints such as the short cut keys from menus, so where you would discover stuff from clicking around in the UI and seeing it, now it frequently seems that you'll never figure this stuff out without googling for an answer.
Error messages, too, have disappeared - back in the day you used to get a descriptive error that told you what broke. Ok, so the non-techies probably didn't understand them but at least they could ask a techie. Over the past few years, error messages have been replaced with generic "something broke" errors that give no one any hints as to what went wrong. Increasingly (especially on Android and iOS) apps don't display an error at all - if something breaks they often just plain don't work and its very difficult to figure out why.
http://blog.nexusuk.org
I bet most projects would be happy to accept patches to their man pages, and files they store in /usr/doc/ if they improve quality or accuracy.
What you say is quite true however it doesn't really get at the root of the problem. If I ever have to consult a man page and I'm not doing something really arcane then the application interface is badly designed. No amount of documentation will ever fix a bad interface.
Then I hire him, after all writing code I accidentally use in my commercial product, and feeling being hold hostage because in a corner area it does not work, is his business model :)
Cost free eBook I read (by iBook/Kobo/Amazon/ObookO/Gutenberg etc.): "The Green Odyssey" by Philip Jose Farmer.
How about crowdfunding some documentation efforts by real technical writers?
A band-aid that doesn't solve the real problem. Even if you did this and produced some great documentation, it would fairly rapidly become obsolete unless the software is never updated. You would have to basically create an endowment to fund ongoing documentation development. The real problem is that A) the interfaces are bad enough that documentation is even necessary in the first place and B) documentation is boring, unrewarding and time consuming to do well so nobody wants to bother.
If someone comes along and gives you a free hamburger, you don't complain that they didn't bring fries and a drink.
But if the hamburger tastes bad and you are not sure what's in it,. you might want to ask. And if you ask and are given an answer like "hey it's free, eat it or GTFO" it doesn't make the giver less of an asshole.
...gis sdrawkcab (usually not responding to ACs; don't bother posting as AC)
Light travels faster than sound. This is why some people appear bright until you hear them speak.........
Free software is....well...free. The people who wrote it don't get paid.
Frequently that is not at all true. Most free software is developed by professional developers in conjunction with their day job. It is released as free but for many important software projects the developer probably actually did get paid for their time. Sure there are a non-trivial number of developers who really are doing it for non-financial reasons in their spare time but the number is far smaller than most people think.
Bad documentation is not unique to FOSS. Commercial software is often just as bad.
Switch all of the info docs back to man pages. man pages are neatly organized and have all of the info in a handy grep-able format. info help pages are as disorganized as 1990's websites with their random hyperlinking. Something GNU got waaay wrong.
On the other hand, I've noticed a steady decline in documentation for commercial software too.
Many of them seem to be going the route of "community-driven" documentation; i.e., dropping the cost of the manuals (and everything related, such as tech writers, printing, and so on), and shifting the burden of educating new users to more experienced ones. This is more or less how most FOSS projects have been documented for years, though out of necessity rather than a desire to cut yet another corner.
Writhe your naked ass to the mindless groove.
Yes, this, especially:
The fact of the matter is the majority of programmers are assholes that have no business operating in normal society.
Well OK, I'll add the caveat of, "the majority of programmers I've asked for help are assholes..."
It's like if your car wasn't acting right, and you took it to a mechanic, and he told you, "just read the fucking manual you idiot." Of course, that doesn't happen, because most-if-not-all mechanics aren't so arrogant they think everyone should know how to fix their own car.
An enigma, wrapped in a riddle, shrouded in bacon and cheese
MOTHERFUCKER, IT DOESN'T WORK LIKE THAT. Fuck you in your goddamn asshole you fucking arrogant fucking pricks...The fact of the matter is the majority of programmers are assholes that have no business operating in normal society. Lock them in the fucking closet and let them read the fucking source until they jizz all over their crusty beards while fantasizing about Stallman's brown pucker.
Just a wild guess here, but hear me out: Is there any chance that your interpersonal skills could have contributed to the lack of communication?
Stop-Prism.org: Opt Out of Surveillance
... and this is why the term "software engineer" is a bit of a misnomer.
Could you imagine if, say, aerospace engineers didn't document their work? Automotive engineers? I can hear the shop talk now:
"Hey, Jim, what's the recommended torque for head bolts on an '09 Madza 3?"
"What's the manual say?"
"Nothing, they didn't document that part."
Ergo, coders who fail to document are anything but engineers, cocky attitudes aside.
An enigma, wrapped in a riddle, shrouded in bacon and cheese
Including the foul language makes it very clear that the poster is biased, and can't (or won't) set aside that bias long enough to have a discussion.
My impression is that the writer sees his contributions as an altruistic gift that the programmers should be absolutely grateful to receive. Meanwhile, the programmer sees the documentation as just another aspect of the project, conveniently being handled by someone else.
Consider, then, a scenario where the programmer has implemented a function only enough to suit his needs, as for a library, but the writer wants to document every behavior of the function, as a writer should. At this point the writer asks the programmer to describe the complete behavior, but the programmer like can't, sa he hasn't defined or cared about behavior outside his necessary subset. This scenario, one of many with the same result, starts a disagreement where the writer expects more support from the programmer than the programmer is willing or able to provide.
Given the verbiage used in this post, we can infer how quickly a discussion about such a disparity of priority would heat up. I would not be surprised to learn that the writer had been dismissed from projects because of his attitude toward the programmers.
You do not have a moral or legal right to do absolutely anything you want.
I think several here have different expectations of what constitutes "good documentation". Being a Linux sysadmin, I work in FOSS day in, day out, and documentation is always available and clear.
Without knowing, you've hit the nail with the hammer.
.pdf document with all possible options.
Here is why FOSS docs are so nice to you, but proprietary ones are not: audience analysis.
The people who create FOSS documentation are often either the developers themselves, or very early adopters who spend a lot of time with the developers. They have a technical mindset, and will write documentation in that way. You have a very technical mindset, and like me, will probably prefer a well-commented configuration example over a nicely formatted
In large enterprises, things are different. That's where the professional technical writers come in (yes, that's a full-time job). These folks will come up with a target audience, secondary audience, initial outline for the documentation and (in their minds) well-written content and examples. Since this gets reviewed many times by people who all have an ego telling them that they must make at least some changes in order to show productivity to their bosses, the documentation ends up being a piece of crap. It may be correct, but it usually is a piece of crap. For example, let's take any routing vendor's documentation. You are looking to configure something as simple as an L3VPN. The easiest way to do this is by getting an example configuration and just change some IP addresses to match your own network, right? Well, the "professionals" think not. They will come up with this:
Step 1: configure an IGP. For more information on how to configure an IGP, see chapter 12, section 3.
Step 2: enable the appropriate interfaces for MPLS. For more information on how to enable interfaces for MPLS, see chapter 2, section 1.
Step 3: create an LSP between the two PE nodes. For more information an how to configure LSPs, see chapter 2, section 10.
Step 4: enable a signaling protocol such as BGP or LDP. For more information on how to configure BGP as an L3VPN signaling protocol, see chapter 10, section 9. For more information on how to configure (targeted) LDP as your L3VPN signaling protocol, see chapter 7, section 1.
Step 5: configure the route-target: set route-target 12345:1. For more information on route-target configuration, see chapter 8, section 2.
Step 6: configure the route-distinguisher: set route-distinguisher 12345:100. For more information on route-distinguisher configuration, see chapter 8, section 3.
And that, my friend, is why commercial documentation sucks a monkey's ass.
I'm not a complete idiot... Some parts are missing.
I think Unix (not just BSD, but I include BSD-based SunOS 4.x) documentation from the mid 90's was the best and easiest to follow.
The main thing I miss from that era is that practically everything I wanted to know could be looked up in man pages; and if not on that first man page I tried, in a meaningful see-also page.
These days, seems most software (not just Linux, but for any platform) is scattered amongst HTML-urls that point to long-gone former websites, and youtube tutorial videos.
Now you might say that much of today's software is too complex to describe in a man page --- but IMHO - that's the bigger problem. If people write complex monolithic bloat, writing pretty documentation for it is the least of our problems.
First, I wanted to link to This blog post by Steve Losh on writing documentation. I think offers some good metaphors as to why 'reading the source', even 'self documenting' source, is insufficient, though of course not everyone will agree with his philosophy.
Second, I wanted to say on the projects that I work on as a systems engineer doing new product development (as in this, not the information technology use of the term) documentation is perpetually threatened. And we usually work on comparatively well funded, non-FOSS programs. Documentation is timing consuming and expensive, and sometimes it is even customer direction to place it at a lower priority than new development. Though inevitably it makes things harder later, sometimes that is o.k. if it works better with the cash flow (saving money now only to pay more later can work if you expect to have more money later). Unfortunately FOSS software projects don't necessarily have people promising a ton of money for the documentation.
Isn't "Documentation" a 4-Letter Word?
docx ?
Intellectual Property is a monopolistic, selfish, and defective concept. It is "tyranny over the mind of man"
Now if only they would push such information to the upstream projects we'd be getting somewhere. Otherwise, that's just one more set of web-pages that needs to be checked.
Pretty annoying if the best way to find out about an application is to have to check the Yggdrasil archives, the Slackware web page archives, the Caldera docs, archives of the Mandrake web pages, Knoppix blogs, etc.
Since there was an 'and' between the main clauses, commas were appropriate.
Yup, I'm convinced JavaDocs are the worst thing to happen to documentation in a long time. They actively discourage good documentation.
There is no good way to have API docs alongside meaningful documentation (with examples, diagrams, longer blocks of prose) without ramming everything into your codebase.
Look at Sphinx (Python's standard for docs - although supports other languages) - it allows you to curate custom docs, and then add in your API documentation from your code. Your code keeps it's core documentation for 'this is how you use this class/function', while your docs actually explain how the system fits together, how everything works.
JavaDocs are like a testing suite that only allows you to do unit tests - it makes you think in terms of the smallest unit, so you never test the whole. Sure, a foo may be passed into the bar, but what does that really mean? JavaDocs are essentially no more than browsing the code with folding enabled.
Good documentation is about all the stuff that *isn't* represented by your code. JavaDocs focus only on what is.
In general, Python is the best example - the documentation is execellent, and tools like DocTests allow you to ensure your documentation is up to date and accurate.
I've never seen JavaDocs that add anything to the source. It's okay if you need a list of methods or parameters, but usage is lacking.
Documentation needs to have several *working* examples (not snippets) from a simple Hello World to more sophisticated but still commonly used. A single example that illustrates every imaginable feature and use case is rarely helpful.
Blame Sun.
JavaDocs have the capability of being used to good advantage, but in actual use, they're really just a loose aggregation of API call specs. And for more recent javadocs, they're often even useless for that. One major product's javadocs are more a pointless muttering about internal implementation details than actual usage information. I've never seen a major library that could actually be properly used based on the information in the Javadocs alone.
Sun did mitigate the uselessness of JavaDocs by supplying tutorials, but the two weren't tied together in a meaningful way.
Then don't use open source. In addition to missing documentation, there is often also bugs and unimplemented features. Unless you are actually working on a project which is built upon open source components, why would you use inferior software?
There is two kinds of freedom: freedom of the source code, and freedom of yourself getting cool stuff done productively.
Ever heard of Red Hat? They don't sell an operating system, they sell fully vetted, stable, documented and supported Open Source solutions that have been well tested. They keep knowledgeable staff and support the development of FOSS by paying them to contribute to various projects they find useful for their customers. You may not like Linux and have no need for Red Hat or companies like them, but I think you too easily discount the level of support available for the major parts of the FOSS universe.
Personally, I've used both Microsoft's and Red Hat's support services and Red Hat wins in my book hands down. I had tickets open for WEEKS with Microsoft that dragged into MONTHS and we didn't get any resolution from them beyond "Just reload the system from scratch and that will fix it". Where with Red Hat, I never had a ticket open for more than 2 weeks and usually had a coherent answer from them in a few days. Your mileage may vary, but IMHO FOSS isn't as big of a problem as you seem to think.
"File to fit, pound to insert, paint to match" - Aircraft Maintenance 101
Sorry folks, we accidentally used dice.com to hire some new sourceforge developer advocates. The official slashdice HR guidelines prevent us from hiring people on dice.com (we don't eat our own dogshit) but the HRtard responsible, umm, well, was hired from dice.com. Rest assured that we're firing all of them and sourceforge will continue to serve the finest adware installers for stable open source projects t(meaning they haven't been updated since the 90s.)
Copyright (c) 1990 - 2014 Dice. All rights reserved. Use of this comment is subject to certain Terms and Conditions.
But that isn't how it works.
The whole FOSS thing is a trade. On the one hand, the coder "donates" his/her/its time doing things that are funAnd when you multiply the time spent by maybe some thousands of users, all trying to work out the same problems - compared to the time taken to write, compile and toss-over-the-wall some of this stuff, "free" software is probably some of the worst deals on the planet.
And as for that old crock: You get what you pay for or "Hey, it's free: what do you expect?", most of this stuff is far from "free", it has a large negative value, as it takes many hours or days of your time just to get up to zero: the point at which you can start to do something useful with it.
politicians are like babies' nappies: they should both be changed regularly and for the same reasons
Only use open source that has good documentation; this is why I prefer BSD over Linux for servers, for example. On the desktop, the major packages I use have great docs. this article mentions some fringe desktop I never even heard of (and I'm a Unix/BSD admin and user for over 25 years and Linux user for 16), there's your problem right there buddy.
Wait, wait. We're talking about different things here.
In a dev house, as you call it, there's going to be different people with different jobs. The developer writes code and comments it, then there's a content writer who does the documentation. Also these tend to be for-profit organizations which don't do much OFSS (if any at all).
What a quaint 20th-Century concept.
We laid all those people off because we're "Lean". The developer's native language is Malayam and the documentation department was dissovled.
Now that server time has reduced in cost, you can add continuous integration to a project and make full documentation a requirement.
For example, here is a CI tool for KDE which tracks missing documentation at English Breakfast Network http://ebn.kde.org/
-- I was raised on the command line, bitch
Autodesk Fusion 360? From what I can see they've got a quite comprehensive and professional learning resource set up.
I haven't generally found that to be the case at all. At least not with enterprise stuff. Generally the company wants you to buy support contracts and training from them so they make operation as obscure as possible. One almost universal technique used to build an internal vernacular for the proprietary product, naming elements and configuration blocks using invented product specific labels instead of using standard industry terms. This is great because someone who is perfectly competent can't make heads or tails of your documentation until they've learned the vernacular you use.
Good documentation in my experience is documentation that any competent programmer/engineer/user can pick up and immediately use without ever having seen your stuff before.
Zed Shaw, is that you? Good to hear from you again!
I've never seen JavaDocs that add anything to the source.......Documentation needs to have several *working* examples
Well there's your problem......you're someone who doesn't learn from reading, you're someone who needs examples.
Javadocs are often useful if you don't want to read through several layers of code to find out what the function returns on error, or if it's safe to pass in NULL, for example. Good ones define the contract for the method, and that's extremely valuable, but contracts are a different topic.
"First they came for the slanderers and i said nothing."
Poster in question here.
First of all, fuck you for being a presumtive cuntflap. Eat dicks and die of the STD of your choice.
Moving on...
When you openly ask for assistance you do not repay your volunteer's effort by treating them like a fucking idiot when they come to you, the expert on the subject, for a goddamn answer. I can't document what I don't understand and if you are the only person in the world that actually understands it what the fuck do you expect me to do?
I got fed up with all of the hostility directed towards me from people that ASKED ME TO HELP THEM that I gave it all the fuck up. The final fucking straw was when one asshole told me to ask questions on the forum because he couldn't be bothered to answer them. What. The. Fuck.
If you don't give enough of a shit about your software to answer one person's question, which would in turn answer the questions of a few HUNDRED people, which would allow you to NOT NEED A FORUM DEDICATED TO FIGURING OUT YOUR FUCKING SOFTWARE then why should I give enough of a shit to write the documentation?
I've never been dismissed from a project because unlike the cuntbunglers that program the shit, I actually act like a fucking professional and DON'T tell them to eat dicks and die of the STD of choice. I simply let them cut their own heads off and go about my business.
Perhaps frustrated tech writers like yourself should get together to form their own group (with blackjack and hookers) which picks specific un/underdocumented FOSS projects and "bombs" them with documentation. Self-hosted if the project devs don't realise what they're getting. Gathering professionals, enthusiast volunteers, through to helpful coders.
Eventually the group gains enough reputation that you can start to make demands of projects, in order to raise the general standard of technical/project and user documentation across FOSS projects. Likewise, tutorials, courses, e-textbooks, etc.
Science is all about firing a drunk pig out of a cannon just to see what happens.
fix it yourself.
How the hell is someone supposed to DOCUMENT something that they're trying to figure out how to make work?
Are you a black hole of utter cluelessness?
No clue will ever escape your infinite singularity of utter incomprehension?
Once a clue passes your event horizon it's never seen again?
Do you emit Hawking Clue Radiation?
Keep going....
Do you have ESP?
No. My communication skills are fucking excellent when I'm not shitting all over someone for being an asshole to me. Believe it or not, not everyone is a boring fuck like yourself. Some of us are actually capable of communicating in multiple ways depending on the setting.
Where do you go for your FOSS documentation and self-help?
To be honest, my answer is often "closed source software from a company that provides documentation and support contacts."
Yeah yeah... open source rah rah read the code and fix it yourself. Fuck that. I have better things to do with my time than trying to decipher and fix some other jackass's code.
Setting up a resource like that doesn't mean that it's filled out in a useful way, and it's not.
If I might review your scenario from a slightly different perspective, we might see why Linux has still not taken over the desktop.
The programmer has implemented something that doesn't fully work, because it's "good enough" and/or the programmer can't be bothered to make it right. The writer, like a normal user, is surprised when a casual experiment fails dismally. The programmer might (in a dream world) be embarrassed by the poor quality of his/her work, or (more likely) reacts with anger at the implied accusation of low quality (rather than accept the input as a feature request/prioritization), which anger is reflected back by the writer inferring that the programmer is not just uncaring but incompetent.
Someone offering to handle documentation *is* offering an altruistic gift of time and effort, just like any other open source contributor, though expecting gratefulness is sort of hopeless, mainly because most programmers would *not* see the documentation as an aspect of the project at all, but as a separate afterthought.
Normal people want stuff to work, and they don't want to remanufacture stuff first to make it work. Normal people assume that "published" or "released" stuff is ready to be used, not an experiment or a hobby project. Yes, they're getting stuff for free; but they're still comparing it against other stuff where people worked on the dull parts as well as the fun parts.
It's like if your car wasn't acting right, and you took it to a mechanic, and he told you, "just read the fucking manual you idiot." Of course, that doesn't happen, because most-if-not-all mechanics aren't so arrogant they think everyone should know how to fix their own car.
Take it to the next step: Mechanics have realized that the benefit of others not knowing how to fix cars is that Mechanics have a skill for which they can ask to be paid. They can be as arrogant as they want about their superior car knowledge, as long as they don't tick off the paying customers. The programmer who has thrown his incomplete hack on a server and called it FOSS is not getting paid, and sees no reason to put in any "extra" effort.
If it is not documented it doesn't ship. If the docs are wrong it's considered a reportable bug.
The man pages and official FAQ's are all you normally ever need.
I have to return some videotapes...
Error messages, too, have disappeared
Users won't understand the error message anyway, just give them a frowny face and be done with it!
"Somebody has to do something. It's just incredibly pathetic it has to be us."
--- Jerry Garcia
JavaDocs are only as good as the person writing the documentation. I've seen useless JavaDocs which were nothing more than a list of API calls, and I've seen JavaDocs that were so well done that it could have easily been published to a book.
These comments are my own and do not necessarily reflect the views or opinions of my employer or colleagues...
Error messages, too, have disappeared
Users won't understand the error message anyway, just give them a frowny face and be done with it!
I don't mind the idea of hiding the error message behind some kind of "advanced" button on the error dialogue, but removing it entirely is just nuts.
http://blog.nexusuk.org
I think you mentioned another reason documentation is lacking in FOSS. It gives an incentive towards paying for support.
These comments are my own and do not necessarily reflect the views or opinions of my employer or colleagues...
I feel you, bro...
...gis sdrawkcab (usually not responding to ACs; don't bother posting as AC)
Money is the answer.
If you were to give me money, I could write all kinds of words for you. Tell me all about the configuration, deployment and best practices for your system and we'll work together on some documentation.
Even as a coder, I've had this problem when trying to contribute to documentation. Even writing howto's for specific use-cases. There are a few good developers out there who are capable of communicating, answering questions, etc. - to help make sure that the documentation I write is accurate. But they're few.
These are my friends, See how they glisten. See this one shine, how he smiles in the light.
And don't take this as a condemnation of Fusion 360 - it's a really useful tool, and it's improving quickly.
It's like if your car wasn't acting right, and you took it to a mechanic, and he told you, "just read the fucking manual you idiot." Of course, that doesn't happen, because most-if-not-all mechanics aren't so arrogant they think everyone should know how to fix their own car.
You forgot the clause "for free" in there. Of course that doesn't happen because there's an expectation that if you bring the car in, the mechanic is going to get _paid_ to first figure out what's wrong with your car starting with the description of "Car no go". So the mechanic gets paid for the time that he takes just figuring out what's wrong first, and paid to then fix the problem (plus parts). (and eventually you find out that the person is trying to use the car to go driving up and down sand dunes in Oregon.... but they are trying to do it in an F1 race car with racing slicks)
They will come up with this:
Step 1: configure an IGP. For more information on how to configure an IGP, see chapter 12, section 3.
Step 2: enable the appropriate interfaces for MPLS. For more information on how to enable interfaces for MPLS, see chapter 2, section 1.
Step 3: create an LSP between the two PE nodes. For more information an how to configure LSPs, see chapter 2, section 10.
Step 4: enable a signaling protocol such as BGP or LDP. For more information on how to configure BGP as an L3VPN signaling protocol, see chapter 10, section 9. For more information on how to configure (targeted) LDP as your L3VPN signaling protocol, see chapter 7, section 1.
Step 5: configure the route-target: set route-target 12345:1. For more information on route-target configuration, see chapter 8, section 2.
Step 6: configure the route-distinguisher: set route-distinguisher 12345:100. For more information on route-distinguisher configuration, see chapter 8, section 3.
And that, my friend, is why commercial documentation sucks a monkey's ass.
Damn, you just described the O'Reilly Sendmail book perfectly! (LMFAO)
It's an excellent reference for someone who knows a good amount about Sendmail already, but even as a fairly advanced admin I find it really convoluted in a lot of ways.
Here's the thing: quality technical writing DOES require specialized skills. It also requires close collaboration with and cooperation from the dev team.
Having worked with a professional tech writer in the past, the process works something like this:
1. Dev team writes the software to meet the business requirements, keeping notes about which requirements are met completely, partial solutions, known bugs, etc.
2. Tech writer meets with dev team on a regular basis, developing draft documentation from dev team notes and business requirements following appropriate style guidelines.
3. At some point, a release is declared. Tech writer completes draft documentation draft for work completed for that release.
4. Dev team and tech writer reviews draft documentation together for completeness and correctness.
5. QA team implements the software in the QA environment PER THE DOCUMENTATION. -- this is the key part. If the documentation is insufficient to implement the software and/or the software does not work as documented, it is a bug.
6. Bug reports are filed against both the software and the documentation as necessary.
7. Release is ready when the software is acceptably debugged and works as documented.
Of course, this hardly ever happens anymore whether software is FOSS, commercial, or in-house, but I have see the process happen, and it is a beautiful thing when it does.
Often the only reliable up-to-date documentation is sadly the source code itself.
Yes there is, other Barry, yes there is.
Of course. I don't mean to suggest that programmers are always blameless. Short tempers are found everywhere.
[Alice] reacts with anger at the implied accusation of [unprofessional work] ... which anger is reflected back by [Bob] inferring that [Alice] is not just uncaring but incompetent.
That's the problem, in a general form. One person offends the other, who retaliates with something to offend the first, and the partnership is doomed.
My point, which I believe still stands, is that from the demonstrated linguistic preference of the writer, it seems likely that he's the sort of person to take offense most easily, and return it in an amplified form, rather than the kind of person to put aside such minor transgressions for the sake of the project.
You do not have a moral or legal right to do absolutely anything you want.
Wow, I totally agree with you, on that. For example, one reason I've always preferred Firefox over IE is that, when it couldn't get connected to a website, it would basically just say "I can't get connected to that site". My first question was always, "well why can't you get connected?". Were you able to find look up the name? Did you get a network error, like "connection refused" or "network unreachable?" Now, Firefox is doing the same thing. Holy crap, is that irritating.
Sit, Ubuntu, sit. Good dog.
Spoken like a snot-nosed coder who can't be assed to explain his delicate genius even to the people hired to listen.
On the other hand, I've noticed a steady decline in documentation for commercial software too. Manuals have gone from the thick reference books I remember from 20 years ago to little "quick start" books if you're lucky. More frequently no documentation at all.
How I miss the days of fat manuals and binders with software In the old (meaning even up to XP) days they even used to ship comprehensive user guides with computers.
It's even effecting games now, both PC and console. For example The manual for the PS3 edition of the GOTY version of Fallout 3 is 43 pages long. The manual for the PS3 version of the Legendary version of Skyrim is a two page pamphlet directing you to http://manuals.bethsoft.com/ where you can get a PDF version, which is slightly over 20 pages long. That PDF is useless on the PS3 itself, of course. Digital downloads are hit or miss. Strangely the PSP was better in that regard.
One set of well done user documentation I have encountered recently is that for Scrivener. Very comprehensive.
Programmers, some of them at least can write programs. Deploying a solution requires more. Architecture, human resource management, scheduling, testing, triage, review, marketing and documentation user support and product management, for example. There are reasons there are such specialisations. Business Cases and Functional Requirements should provide use cases or stories, which inform your testing and provides the skeleton of your user manual. You do start a project/phase/update/maintenance by understanding the requirements, right? You accept the output by validating it against the original impetus. And then you describe it in something of a narrative. Whether you sprint, spiral or fall over water, this works.
Dialectician. Archology.
It's that simple. If documentation cannot be kept up to date and accurate, I cannot rely upon the software, and will not touch it period.
Still waiting on Serviscope_minor to wake up to fucking reality and realize that Jessica Price isn't going to fuck him.
I think that's *half* of where the problem started.
The second half is when various Linux distros started writing their "own" documentation, rather than contributing back to the upstream projects.
Once documentation fragmented like that; every damn blogger started trying to make documentation "his" to preserve his own page-rank; and a bunch of commercial Question/Answer sites saw the business opportunity of trying to own the documentation for themselves.
Once all those were in place -- it seems most of the efforts moved away from contributing documentation back to the source projects, and moved towards commercializing and monitizing "answers" - which is only profitable when the documentation doesn't keep up.
Sad.
I was really concerned about the sorry state of the Bugzilla documentation a decade ago. So I wrote first an unofficial FAQ, and then later a book called "The Bugzilla Guide" and submitted it to the CVS repository under my own copyright. A few years later when I felt it was in a reasonable state, I released the documentation to the Mozilla Foundation and washed my hands of the project. They've done a pretty good job keeping it updated; SOMEBODY has to do the groundwork to create a framework for the documentation to hang together. It's either a labor of love or a labor of money. Lucky for me in writing The Bugzilla Guide, I had both: first was paid to work on it part-time as part of my job, and then for several years with no remuneration. Eventually I stopped using the product professionally, so therefore had no need to revisit and update any further. The tale is the same for many of us, I believe. I parlayed that experience into a series of lucrative contracts that leveraged the fact that I was the guy who "wrote the book on Bugzilla". These days, I have largely stopped doing contract work on the basis of that anymore; my full-time job -- that, not coincidentally, involves writing a lot of documentation! -- is way too interesting for me to spend more time on that :-)
So in short: find a personal or professional reason to use a product and write the docs. If you don't do it, who will?
Matthew P. Barnson
I learn what I think when I read what I write
It's like if your car wasn't acting right, and you took it to a mechanic, and he told you, "just read the fucking manual you idiot." Of course, that doesn't happen, because most-if-not-all mechanics aren't so arrogant they think everyone should know how to fix their own car.
Take it to the next step: Mechanics have realized that the benefit of others not knowing how to fix cars is that Mechanics have a skill for which they can ask to be paid. They can be as arrogant as they want about their superior car knowledge, as long as they don't tick off the paying customers. The programmer who has thrown his incomplete hack on a server and called it FOSS is not getting paid, and sees no reason to put in any "extra" effort.
That's like saying if you have a friend who's a mechanic, and he, say, changes your spark plugs for free, he "sees no reason" to put the plug wires back on, since that would be "extra effort."
Funny you put it that way, since there seem to be a lot of people who "work" on a FOSS project as resume fluff. Ignoring the documentation because it's "extra effort" would, to me, tell a potential employer that you're lazy and tend to half-ass your projects.
An enigma, wrapped in a riddle, shrouded in bacon and cheese
It's like if your car wasn't acting right, and you took it to a mechanic, and he told you, "just read the fucking manual you idiot." Of course, that doesn't happen, because most-if-not-all mechanics aren't so arrogant they think everyone should know how to fix their own car.
You forgot the clause "for free" in there.
I forgot nothing. As a mechanic, I work on my friends and families cars for free all the time, but I don't see that as an excuse to be an arrogant prick nor half-ass my work.
An enigma, wrapped in a riddle, shrouded in bacon and cheese
Heh. I wish that I could blame it on Github. Unfortunately the problems I encountered were with mainstream distribution prepackaged software from the stock repositories, not some third-party-sourced stuff. When core stuff like the display manager are heavily modified, they at least need their configuration and usage well-documented. I'm not a programmer so I'm not working directly with the libraries or functions myself, but if it's not even clear how to manage the configurations from a sysadmin perspective then it's useless.
Do not look into laser with remaining eye.
yeah, and pretty inflexible.
CLI paste? paste.pr0.tips!
Your sig annoys the hell out of me, could you finally s/Unix/Linux/, or even s/Unix/Slackware/ it, please?!
Repeat after me: Linux is not Unix. It does not even try to be. And frankly, this very Ask-Slashdot brings up of the main difference between Unix and Linux; namely the point that the Unix documentation (Nowadays the BSDs' for most practical purposes) is largely fine, and well-maintained.
So all your sig does is making yourself look like an idiot, and worse, it does it in a supposedly smug way.
Your sig is fail. Thanks for considering.
CLI paste? paste.pr0.tips!
I actually prefer it that way. Simple enough for the knowledgeable, with drill-down capability for those who need more detail about step X or have a custom configuration that needs taken care of.
Beats man pages anyway.
...gis sdrawkcab (usually not responding to ACs; don't bother posting as AC)
Oracle software is particularly bad about this, as well as being broken in ways that make it almost nonfunctional for many of it's advertised purposes.
Really?
http://www.oracle.com/technetw...
http://docs.oracle.com/cd/E282...
Yes, Oracle documentation is inherently complicated, because its products are very complicated. Comprehensive documentation tends to be that way.
...gis sdrawkcab (usually not responding to ACs; don't bother posting as AC)
I wouldn't say that today's software is too complex for man pages but instead man pages have never really been ideal for the tasks for which they're used. Software has always been complex. Man pages might have been appropriate for some short window of time but technology quickly left them behind.
Man pages do not have an effective system of hyperlinking, indexing, or even searching. They were meant to be read on a teletype or printed on paper. For documentation any more complex than instructions on how to use console commands they are completely inadequate. Even for looking up instructions on console commands they're less than adequate because there's no sort of authoritative hierarchy, if you don't look up the exact right term man won't point you to the correct documentation (or best guesses).
Besides man being inadequate it is difficult to write proper man pages. This is just adding insult to injury as it makes it less likely that developers will write even bad documentation.
Of existing documentation systems I'd most like to see GNU Info become the primary documentation mechanism for FOSS. It solves most of man's problems without introducing its own new ones. Even GNU Info isn't perfect and could use some improvements.
I don't disagree with the idea that FOSS desperately needs some reliable offline documentation. This idea might require that FOSS distributions themselves maintain their own documentation. The Arch wiki for instance is fantastic, it's some of the best Linux/Unix documentation around. While the Wiki is great it would be really nice to see this information turned into texinfo/manpage/whatever files so everyone could have good references and not need access to the internet.
I'm a loner Dottie, a Rebel.
Yup. And that's been the other part of the problem, poor versioning on the writeups that are out there, so there's a bit of research just to see if this document even applies to the project, package, and version that you're trying to work with. Since I was working with video, notorious for knocking down the local console to the point that a reboot is required, I decided to set up a serial TTY so that with my old laptop I could serial-console in. In the process I found instructions for configuring the bootloader to also use the TTY interface, but while Grub2 is better documented than a lot of projects I still found some erroneous documentation for Grub2 and some now-useless documentation for the first-generation Grub as well.
Do not look into laser with remaining eye.
This seems pretty perverse. If a developer doesn't write documentation because he doesn't like to, how does that make him an asshole? You're the one who is asking him to do more work, for your benefit, for free.
I spend a lot of money on books. O'Reilly, Packt, etc. put out some very useful books documenting FOSS tools (and for statistical computing in R, both Springer and CRC publish a lot of really excellent books, although they can be very pricey). These books are mostly written by people who can really write and edited by people who can really edit.
And when I spend my money buying this kind of documentation, it supports a culture of good technical writing and ensures that good technical writers to get paid for their work.
It might be nice if there were a similar quality of documentation available for download under CC, but absent that it's nice that there is a thriving industry providing good, useful documentation in books.
I developed my chops working with MS-DOS in the early nineties as a kid, starting with version 3.3, which lacked an online help system. I had an MS-DOS manual that covered a whole lot of what could be done, and then when I moved on the MS-DOS 5 and online help appeared, I found it to be decent even if not great, and it only got better throughout the versions, until I stopped using DOS.
Maybe my perspective is a little skewed, but I like documents that decribe usage concisely, and I like examples when the usage can't be described concisely. It's okay if the complexity of a product or project can't be describe concisely, so long as good examples exist. When I first started using Linux it was Slackware back in the 2.0.0 kernel days, and I found that my UNIX-in-a-Nutshell book worked quite well even if there were a few things that didn't apply because of the System V vs BSD nature of UNIX as compared to whatever init Slackware used, plus the whole commercial UNIX versus GPL versions of things situation.
I totally get that if software isn't improved over time that it could die-on-the-vine, through lack of use over time, but those changes need to coincide with usage docs. If they don't then things could die-on-the-vine as they get too out-there for people to easily use.
Do not look into laser with remaining eye.
If source code was written in human language I'd agree.
As someone that has factory service manuals for every vehicle owned, and probably a few for vehicles that are long-gone, there's a difference between an owner's manual and a factory service manual, and most FOSS projects lack both, or lack the Owner's Manual and the first couple of chapters for extended but common maintenance service of the FSM.
Both general-use manuals and in-depth manuals have their places, but the manuals that don't exist don't help very much. To continue the car analogy, I may not need to replace the high-reverse piston in the transmission's front planetary sun gear, but I would sure like to know how to change the filter and fluid, and how to remove and reinstall the transmission without accidently dropping the torque converter on my face.
Do not look into laser with remaining eye.
[First half: Info replacing man.]
[Second half: Distro-specific Linux documentation explosion and lack of upstream transmission.]
And the THIRD half: The X windows system dumping every little subroutine interface into the man pages, with names that collide with unrelated non-X features, so the "apropos" command became buried in junk. B-b
Bantam Dominique roosters crow a four-note song. Once you've heard it as "Happy BIRTHday" you can't NOT hear it that way
Let me tell you a little story.
We use Visual Studio 2012 here, and not long ago somebody told me a neat little editor trick. I looked at the menus, on-line documentation, Visual Studio books on Safari, and the MSDN site, and didn't see any reference to it. I wondered if there were others, so I asked a question on Stack Overflow asking if there was thorough documentation of the VS2012 editor like there is for emacs and vim.
The question was downvoted. Two people voted to close for "off topic" before I pointed out specifically where the guidelines said such questions were on topic. People simply didn't understand what I was looking for, like it was inconceivable that such documentation could exist.
This is after years of hunting through the MSDN site to check on things, and failing to find what I needed to know about half the time, on the web pages that the information belonged on (either on the page or through links from there).
So, you'll forgive me if I look at TFS and snigger uncontrollably.
"When you have eliminated the unacceptable, whatever is left, however improbable, must be the truthiness" - Holmes
We use Visual Studio 2012 here, and not long ago somebody told me a neat little editor trick.
Well, don't hold it to yourself: Share it! We use VS2012 as well here, so I am curious.
Again, mindset.
Documentation should not be perceived as "optional bone thrown to the hungry masses". It's part of the process. You actually START with it, during the design phase. You explain how the application works, to yourself, then as you code you develop that document as well.
My project already has 3 large mindmaps where I write everything, from descriptions to formulas to examples. That is before one single line of code is written, and each column, table and SQL script has descriptions and explanations. Is it tedious? Hell yeah. Is it helpful? Enormously so. My time spent writing megabytes of plaintext is time saved while developing and building a wiki later on.
And if, months or years from now, I get bored or caught up in something else, someone else could simply pick up from where I left and continue developing right away, the chances of that happening being directly proportional to the clarity of documentation.
...gis sdrawkcab (usually not responding to ACs; don't bother posting as AC)
How I miss the days of fat manuals and binders with software
But that's just nostalgia, digital documentation is much more efficient and effective. You can quickly search the entire contents, it isn't wasteful, it doesn't take up heaps of space and you can take it with you wherever you go easily.
The big joke is that half of what you need to do for documentation, you need to do for regression testing. Might as well explain what you are testing and why.
ID: the nose did not occur naturally, how would we wear glasses otherwise? (apologies to Voltaire)
The problem with software documentation is exactly the same as it was over 30 years ago. This is not to say that software documentation is bad, in fact most are surprisingly well documented with the main problem being the user (oh dear!). Now let me explain why I said this.
When an application is designed (hopefully), written and documented there is a percentage of time that is allocated to all three attributes and usually the smallest percentage is (you guessed it) the documentation although the initial design should be the groundwork for the documentation in the first place. However no matter how well documented a software product is, you are always going to have detractors saying thing like "The documentation is obscure" or "There is not enough documentation" or "The documentation is too long". Usually the detractors fall into attitude of "The application should be so good I don't have to think or do any reading anyway".
The author of the article gives an example of LightDM which has fairly meagre documentation if you go to the web site. Oh the horror (sigh!). Well the application is a "Desktop" which can be likened to Gnome, KDE, Xfce and even Microsoft Windows. In this particular case you normally have a system setting GUI or you can go to the web for more information. If you do a Google search on LightDM you get something like 472,000 hits so there really is no excuse for saying that there is not enough documentation and information.
Personally I don't blame the so called technical elitists from saying RTFM (coined well over 30 years ago) and then come to me if you can't find what you want. The last bit is what I normally say as well and many users seem to have selective deafness. With the Web and decent search engines getting information could never be easier, the problem is that many users who complain don't seem to want to use their brain.
There ain't no such thing as proprietary standards only proprietary formats. Standards are by definition open.
Yes, but it's more likely that numerous years of experience have soured the person on developers.
In the past, Anonymous Coward has been on both sides of these types of issues. But in this case, I think maybe AC has a point.
Developers do have a certain perspective. If you can't figure out how to use something, you really shouldn't be writing documentation. Documentation should be written by someone who can put information together in a sensible, readable way. And if you can't, then you shouldn't.
As a developer, I can list a hundred questions I've asked of applications. Is this supposed to work? Is this supposed to do anything? The label says this but it does this?
Fuck you, read the code. Fuck me, read the code. Fuck us all.
I guess it's time for an undercover sting to see if volunteer documentors are treated like hell.
Care to bet?
Your sig is fail. Thanks for considering.
Your post has been taken into consideration
"First they came for the slanderers and i said nothing."
Here is why FOSS docs are so nice to you, but proprietary ones are not: audience analysis.
Exactly. The OP gives himself away when he describes his computer use as a "home hobby".
As a pro, I much prefer the nice, succinct, "straight-to-the-point" man pages that you find with open source stuff than the tediously long novels that come along with commercial software.
I'm sure hobbyists would prefer a "for dummies" version, but I just don't have the time to read 30 pages of rambling bullshit just to figure out what the "-x" command line option does.
Personally, I think OSS documentation is, for the most part, exactly what it should be.
Alternate answer:
Docs for commercial software are written by professional "technical writers". Many of them paid by the hour. ALL of them incapable of understanding the details of what they're writing about. Their job is to describe the software to the least common denominator. Many times, the person writing the documentation IS the least common denominator, and couldn't make good use of it to save their life. What they do understand, is that the more words they put in the doc, the bigger their paycheck. So you end up with 750 pages of bullshit that doesn't actually explain how the program works.
OP should fire up a Linux system and type "man rsync" and "man bash", read them top to bottom, and then ask himself why his own inability to comprehend that excellent documentation leaves him thinking that OSS docs aren't up to par.
Might require that FOSS distributions themselves maintain their own documentation.
I rather the distributions stay away from this -- or at most just passed whatever documentation they do add to the upstream projects.
IMHO the biggest *problem* now is that you often have to got to Red Hat's manuals, or to Arch's or Ubuntu's wiki, or to Gentoo's mailing list, etc. to find documentation to anything.
Seems like that means you have a half-dozen competing efforts that all are re-envengint the same documentation; and since many of those distros are commercial enterprises, are motivated not to share and to paywall off their investment. Ugh.
Documentation could improve a lot faster and better if some company took the time to setup a Wikipedia-type "Linux Encyclopedia". Everyone could get at it and improve it in waves in the very same way, and it would unite stuff that's scattered hither and thither.
"You must try to forget all you have learned. You must begin to dream." -- Sherwood Anderson
Damn, you just described the O'Reilly Sendmail book perfectly! (LMFAO)
It's an excellent reference for someone who knows a good amount about Sendmail already, but even as a fairly advanced admin I find it really convoluted in a lot of ways.
To be fair to O'Reilly, it's convoluted because it's about Sendmail.
No admin in their right mind would choose Sendmail these days. For a small installation with no budget, Postfix can do the job and is much simpler to admin. For a large installation, you either get the higher-ups to fork over the dough for CGP, or start firing off resumes.
In this day and age, being a sendmail admin == being a masochist.
Intellectual Property is a monopolistic, selfish, and defective concept. It is "tyranny over the mind of man"
Are you reffering to copyright or patents? Second are monopolistic, true, but copyright is not monopolistic at all: it allows for remixes, and implementations that do something the same way but are not just a simple copy.
Defective? Please name a better model. Current implementation has certain issues (terms too long for both patents and copyright, strongly national, problems with alternative models like open content, penalties far too high), but the principle itself isn't broken.
Why is it a "tyranny over the mind of man"? I'm not reffering to DRM or trolling patents (almost all software patents are trolling or defensive-trolling). I think copyright creates incentives to create Intellectual property. Would an author write a book when he knew he wouldn't get any money from its sales? Would you put research money into a drug when your competition could copy it the moment you release it to the market? What are your ideas to redesign these systems?
When I find a problem, I fix it where possible, and at least bring it to the attention of relevant people where I can't.
If people actually did this, instead of complain that "the docs suck" and expecting someone *else* to do the work to fix the issue, the docs wouldn't suck.
If whatever it is uses some particularly arcane and awful docs build system I'll often just send in textual changes. If it uses something sane, or something insane that I already know (docbook for example) I'll send a patch.
This is a case of JFDI.
Agreed. You can produce good docs without the solid co-operation of the dev team, but it's much more difficult, more time consuming, and a lot more frustrating. They also tend to bit-rot a lot faster.
But that's just nostalgia, digital documentation is much more efficient and effective. You can quickly search the entire contents, it isn't wasteful, it doesn't take up heaps of space and you can take it with you wherever you go easily.
Nothing wrong with digital documentation. My complaint is frequently *no* documentation.
http://blog.nexusuk.org
Wow, I totally agree with you, on that. For example, one reason I've always preferred Firefox over IE is that, when it couldn't get connected to a website, it would basically just say "I can't get connected to that site". My first question was always, "well why can't you get connected?". Were you able to find look up the name? Did you get a network error, like "connection refused" or "network unreachable?" Now, Firefox is doing the same thing. Holy crap, is that irritating.
I'm finding that on tablets, things frequently simply don't work - no errors or anything. The iCloud stuff, for example - if it can't connect through to the internet (because it isn't playing nice with a proxy server, for example) then it simply doesn't synchronise; no indication why it isn't working, or that there is anything wrong other than the fact that you notice it isn't synchronising. And yes I know there is an event log hidden away that has debugging info in it, but asking a customer to find that and read out relevant detail is a lot harder than an on-screen error message.
http://blog.nexusuk.org
I really am not sure what you are saying.....the Javadocs for Java have served me well.
"First they came for the slanderers and i said nothing."
Never attribute to malice what is adequately explained by ignorance.
Paradoxically, the ignorance in this case is a result of the opposite: too much knowledge!
Programmers tend to think in code. Many have never had the need to think about the problem they're creating code to solve in any other way than in terms of code. To inexperienced programmers, code may be the *only* way they have encountered to think about software. Consequently, they may have a lot of trouble envisaging other ways to talk about what the software does, how it does it, or why it does it; let alone imagining how such other ways could be useful.
That is tunnel vision, but not necessarily anal retentiveness - it may simply be a result of lack of exposure to situations in which the level of detail that code provides is more of a hindrance than an advantage, such as teaching other people how to use the software.
This attitude is why every single piece of free software that is widely in use (Firefox, Ubuntu, Android, etc.) is developed and distributed by commercial companies. Community-driven development is good at fixing bugs, but sucks when documenting or supporting.
> SourceForge
What year is it?!
To our glut of Unemployed English Majors.
I'd rather have good docs and bad tools instead of tools that claim to be ready for users that are poorly documented. I have just experienced yet another instance of bad documentation and indeed how developer choices contribute to both poor documentation and poor software.
FOSS and Linux eontail a lie. It is somewhat like a social media lie that a community can arrive at quality products just by the need they express and the solutions they generate. I have been using Ubuntu since 8.04 and my 12.04 just fell off the end of the repos, The means I get the "Untrusted Package" nonsense from the Soiftware Center for any new package I try to install. This is Cannonical's sneaky way to telling you that your need to reinstal; it isn't a matter of upgrade because the next rev. they allow you to use is 12,10, and that is not supported. Now this would not be so bad if they allowed /home to be in its own partition by default, but they don't help you with that. When Ubuntu installs, it needs a swap partition, so why can't it ask if there is a separate /home or make one?
There is a FOSS tool called recordmydesktop that claims to do desktop video capture with sound. It fails to capture sound at all on U. 12,04 and 14.04 installs I have. The documentation is a night mare because the program has a lousy interface is was a hacked command line tool with many many options, To get into sound on most Linux systems is a nightmare again because of complex command-line options. It is very hard to figure this stuff out and the way FOSS works if it gets on the Debian repositories it is propagated everywhere, Ubuntu, Mint, etc., etc., with no standards for utility and quality of documentation. That is why FOSS and Linux suck and suck even more as time goes on. My eyesight is failing and to read complex man pages and use command-line options is literally getting to be a pain. I am convinced that much of this is unecessary and is due to geeks not finishing what they started or not really dealing with proper choices in the first place.
Go to You Tube and look for a video that came from the SciPy 2013 Conference from Austin Texas entitled something like "Write Buggy Software". This describes the problem very well and the challenge not met by developers to write simple tools first and use bug reports to tell them who their users are and what they expect from the tool. Too often especially on the Debian repositories I down load something to try that disappoints because it either does not do what it claims or it is too complex to use. The developer has lost the forest for the trees because the underlying driver environment was buggy or he added too many choices each one of which multiplies the chance for bugs. He becomes overwealmed, having bitten off too much, and walks away, and yet the software remains on the repositories.
I am seriously consider leaving the world of Linux, I have used and managed early UNIX systems and nearly all Solaris systems, so I am not afraid of the command line. I just think that the systems ought to be more robust and easier to maintain in config. I am seriously thinking about getting rid of all of my Linux installs and getting a Mac as my main desktop. I have had a Mac before, OS X 10.4, Power PC Mac Mini, but that is a white elephant now, but I may get a current Mac Mini or a Macbook of some kind. The reason is that UNIX and BSD are still under the hood, and FOSS stuff installs there, I can get a Terminal when I want to use the shell, all true, but the big plus of OS X in my experience is that Apple has assured that an application it supports will install and configure reasonably on its hardware. My hint to Apple is that you can undercut poorly supported Debian derivative Linux installs by cutting the cost of Mac hardware by one half. Then it would become an attractive alternative to Linux and Microsoft Windows, and that the way in is that support of apps on a stable platform.
Javadoc isn't meant to add to the source, it is supposed to be instead of the source. You shouldn't need to read and decipher the source code in order to use an API.
All I want is a secure system where it's easy to do anything I want. Is that too much to ask ~~ Randall Munroe
Its free, take it or leave it. .
I think, with your attitude, I'll leave it.
Please tell me what Open Source project(s) you work on so that I can comply.
All I want is a secure system where it's easy to do anything I want. Is that too much to ask ~~ Randall Munroe
What one posts on a site like Slashdot isn't necessarily an indication of how they interact professionally.
Agreed. I think several here have different expectations of what constitutes "good documentation". Being a Linux sysadmin, I work in FOSS day in, day out, and documentation is always available and clear.
As soon as I dip a toe into proprietary software, I'm met with a stubborn inability to communicate from the publisher. NVIDIA, HP, Microsoft, rank about the same in terms of opacity. Even Red Hat's documentation of their proprietary products are no match for the exact same company's contributions to FOSS documentation.
But then there are other FOSS products that match proprietary for its lousiness in documentation. Ganglia, Puppet, I'm looking at you.
My frustration with Fedora is the locked in attitude to documentation preparation and editing. Some of the grammar stinks, and some of it is just plain missing or two generations late.
Fedora uses software tools (I did not see GIT in there) and a closed team to writing and translating. I did not see much in the way of editing being possible. A much much superior approach, in my opinion would be to use Wordpress or Wikapaedia (or a clone) to allow a community of users to revise the writing and editing of the documentation.
All in favor of having Wikapaedia as the documentation management system for FOSS say AYE!!!
Aye (from Montreal)
Leslie Satenstein Montreal Quebec Canada
I think several here have different expectations of what constitutes "good documentation". Being a Linux sysadmin, I work in FOSS day in, day out, and documentation is always available and clear.
Without knowing, you've hit the nail with the hammer.
Here is why FOSS docs are so nice to you, but proprietary ones are not: audience analysis.
The people who create FOSS documentation are often either the developers themselves, or very early adopters who spend a lot of time with the developers. They have a technical mindset, and will write documentation in that way. You have a very technical mindset, and like me, will probably prefer a well-commented configuration example over a nicely formatted .pdf document with all possible options.
Our local colleges and universities demand documentation in the source. Typically, doxygen is the tool. With doxygen, html, pdf and man documentation can be relatively easily prepared. And the reason it wins my support is that one documents the code while the information is fresh in the mind. Software updates are documented in place, and with one "make" program call,the new revised documentation is created.
In large enterprises, things are different. That's where the professional technical writers come in (yes, that's a full-time job). These folks will come up with a target audience, secondary audience, initial outline for the documentation and (in their minds) well-written content and examples. Since this gets reviewed many times by people who all have an ego telling them that they must make at least some changes in order to show productivity to their bosses, the documentation ends up being a piece of crap. It may be correct, but it usually is a piece of crap.
For example, let's take any routing vendor's documentation. You are looking to configure something as simple as an L3VPN. The easiest way to do this is by getting an example configuration and just change some IP addresses to match your own network, right? Well, the "professionals" think not. They will come up with this:
Step 1: configure an IGP. For more information on how to configure an IGP, see chapter 12, section 3.
Step 2: enable the appropriate interfaces for MPLS. For more information on how to enable interfaces for MPLS, see chapter 2, section 1.
Step 3: create an LSP between the two PE nodes. For more information an how to configure LSPs, see chapter 2, section 10.
Step 4: enable a signaling protocol such as BGP or LDP. For more information on how to configure BGP as an L3VPN signaling protocol, see chapter 10, section 9. For more information on how to configure (targeted) LDP as your L3VPN signaling protocol, see chapter 7, section 1.
Step 5: configure the route-target: set route-target 12345:1. For more information on route-target configuration, see chapter 8, section 2.
Step 6: configure the route-distinguisher: set route-distinguisher 12345:100. For more information on route-distinguisher configuration, see chapter 8, section 3.
And that, my friend, is why commercial documentation sucks a monkey's ass.
BRAVO. Also you forgot jargon and abbreviations without a glossary to describe what it is you mean by the "Gronk" function. The Gronk function, by the way is a fixed up fubar function.
Leslie Satenstein Montreal Quebec Canada
Obvious solution to poor documentation: don't read it!
.
There's a lot of decent, good and even excellent documentation to read too, after all. Why would anybody read the bad documentation instead?
I think today many people utilize either realtime chat/IRC etc or email lists or even facebook to share or exchange info on how to do things, solutions to bugs or misconfigurations etc. Look at YouTube and how immense the number of training & how-to video's are there now on anything from OpenStack to LXC.
Yea, "neat little tricks" tend to be undocumented for a reason.
The little trick was control-hyphen to go back to where the cursor had been after a jump (such as "Go To Definition"). Quite useful
I don't know how intended or official this behavior is, and the reason I don't know is that there is apparently no source of truth on what the VS editor is and is not supposed to do.
"When you have eliminated the unacceptable, whatever is left, however improbable, must be the truthiness" - Holmes
As someone else already pointed out, doc writers for FOSS projects tend to be technical-minded early adopters who are either developers themselves, or who spend a lot of time with developers. That's how I got my own start, and it has come with the dual problems that my writing is too technical for Joe User on the one hand, and on the other, when you start documenting new software, you find a LOT of bugs. If you have any coding skills at all, it's faster to go fix the bugs than wait for someone else to do it, and that's how doc writers morph into developers morph into project managers. I haven't updated my documentation in almost 10 years, because only so many hats fit on my head at one time.
As a project manager, the problem I've faced is that I have dozen of peoples who loves my project and woulds liking to help in some way to be part of the team. These generous peoples is wanting to help very muchly, but they isn't writing so good in English, because they isn't talking English as first language. Really interesting it is getting when collaborating are peoples from two very distinctive language background who makes error in strangely conflicting way too. Resulting is documentation need to be heavily edited, to the point of rewriting everything. Them peoples is nice, but they isn't no use writing nothing.
It has been a really frustrating ride over the years. We could do better on documentation if I took the time to sit down and go through it all, but if I had that much time, there are so many more critical things to deal with first. What it all amounts to over the span of almost 15 years is a slow process of attrition and collapse where more people leave than join, and more and more unfinished work piles up everywhere.
It is what it is. If you don't want to deal with all this, go spend $1,000 on some commercial stuff.