Ask Slashdot: What To Do About the Sorry State of FOSS Documentation? 430
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?
*BSD has best-of-breed documentation. (Score:5, Insightful)
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.
Re: *BSD has best-of-breed documentation. (Score:3)
Re: (Score:3, Insightful)
This is impossible. In the Linux world, everything is always a moving target. The reason that *BSD documentation is good is because things are often designed, implemented and then documented. The FreeBSD handbook does get revised frequently, but usually just to document enhancements rather than complete changes in how everything works.
For a Linux distro like Ubuntu to have stable documents, they'd have to actually stick to a sound system, init system and so forth for awhile and not play musical chairs.
Bring back man pages as the primary documentation (Score:4, Informative)
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.
Re:Bring back man pages as the primary documentati (Score:4, Insightful)
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.
Re: (Score:3)
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 eff
And the THIRD half... (Score:3)
[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
Real men (Score:4, Insightful)
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.
Re:Real men (Score:5, Insightful)
That's because documentation isn't fun or glamorous. Everyone developing FOSS wants to do all the fun programming stuff. But no one wants to do the boring hard work of documentation, UI polishing, promotion/marketing, etc. That's why FOSS tends to suck in those areas compared to the commercial stuff (where they actually pay technical writers, designers, marketers, etc.)
Re: (Score:2)
Nobody said only FOSS projects have shitty documentation.
It was implied:
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.
Though it's possible that OP was in prison for 10 years (he doesn't actually say why he was out of home hobby computing), I didn't see any reason to jump to that or some similar conclusion.
No shit, troll.
That word. I do not think it means what you think it means. Calm the fuck down, kid.
Ya get what you pay for (Score:2)
So fix it (Score:2, Interesting)
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.
Re: (Score:2)
Or, for the less altruistic out there, write tutorials, put them on your own blog and youtube, link them from the project's wiki in a reasonable, completely non-spammy way (e.g. copy the content, attribute it to your blog with a clearly marked external link), and make a dollar or two from advertising.
Or, if you have the money to spend, offer a bounty [bountysource.com].
Software Documentation is bad everywhere (Score:4, Insightful)
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.
Re:Software Documentation is bad everywhere (Score:4, Insightful)
"documentation is bad everywhere" is one of those lies developers tell themselves to help them sleep at night. There are programs out there with outstanding documentation. (For example, as a grad student who had never toughed MatLab before I was easily able to teach myself in about a week by just scrolling through the help files.) It's just that those programs are rare, and almost none are FOSS.
This makes sense, because involvement in projects is voluntary, and contributors choose where to dole out their time. There are generally no "customers" with a carrot and stick to make the developers sweat about their failures and oversights. It makes sense that almost no one choose to spend time documenting. Even if they understand that it's a necessary pain, no one wants to be stuck doing in.
The solutions would have to be institutional. I can't think of a single OS project I've seen that had something like "decent documentation for new features" as a gating condition for a major release. That kind of cultural change is hard (and unlikely), but needs to be done if anything is to be accomplished. The only alternative is automated documentation, which doesn't really do anything more than re-state the source code in a different form. It's still only useful if the developers are religious about updating meta-code comments, which they never are.
Re: (Score:2)
I would think there should be automated ways to generate documentation based on the specifications and requirements.
For example, if you're using an "agile" approach, and have your list of stories that need to be addressed, and the developers then create a list of tasks in order to address those stories, the tasks should have enough information to describe what they're doing.... not necessarily implementation details, but if they're writing a function for example, it should document what gets passed in and
Re: (Score:3)
Agile stories don't make great documentation because of their focus.
Story 1: Enters a transaction in a state which doesn't have county level sales taxes.
Story 2: Enters a transaction in a state which does have county level sales taxes but neither the county nor municipality impose one.
Story 3: Enters a transaction in a state which does have county level sales taxes the muncipality imposes one but the country does not.
etc...
Mattes a great deal to the software but you are exposing the abstraction. The end
Re: (Score:3)
The stories would be of the form:
As a user, I want to change my password...
But they generally won't say that the means to do that should be a link from the user account page or what the steps of the process would be. Now for something simple like a a password change, there are generally well defined industry best practices that both the developer and the end user are probably aware of and so both have a common conception of what should happen. That isn't true for functions specific to the application or d
Re: (Score:3)
... generate documentation based on the specifications and requirements.
What are these strange and mystic words you use?
Re: (Score:2)
But the documentation if complete would probably be just as large if not larger then the code, and just as complex to read.
If that's what it takes, then so be it.
Re: (Score:2)
There are three basic levels (bunch of gray in between): Basic, Intermediate and Advanced.
Basic usage (80%) can be simple easy to follow instructions. The next 15% is Intermediate use, which requires Proficiency at Basic Level, followed by Advanced, which requires proficiency at Intermediate levels.
Most documentation is designed for Intermediate/Advanced users OR basic only.
Re:Software Documentation is bad everywhere (Score:5, Informative)
Not everywhere. One free software project has the best documentation [postgresql.org] I've ever seen. We need to point people at shining examples of excellent documentation so they can realize how important it is.
Re:Software Documentation is bad everywhere (Score:5, Insightful)
Have you ever USED IBM, Oracle or MS software?
I've run into scenarios with both IBM and MS where I'm looking for a specific error code, and I get into this:
Q: What is ERR:174027?
A: That's EDONTKNOWWTF
Q: What is EDONTKNOWWTF?
A: That's ERR:174027
*Bashes head into wall*
Commercial software might have better documentation, but a lot of the help still comes from blogs of people having the same error, which IS NOT documentation!
Re: (Score:3)
Nonsense! Professional software uses professional tech authors. I've never had any documentation issues using IBM, Oracle and Microsoft development environments.
lololololol
A Wiki is not Documentation!!! (Score:2, Interesting)
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.
Yes! (Score:5, Interesting)
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.
Re: (Score:2)
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.
I do wonder which projects. My experience has been the opposite: providing detailed information and reasonable evidence that I'd read the document has always produced helpful, thoughtful responses (even from Theo de Raadt himself).
Have you been asking the original developers or on various forums?
Re: (Score:2)
Re: (Score:3)
The Ubuntu forums overflow with very friendly idiots who cannot do anything but post "I have the same issue", or cargo cult solutions that are out of date.
Re: (Score:3)
Re:Yes! (Score:5, Interesting)
True words, I've seen people who behaved like that.
Here's a funny story that I was involved in a couple years ago.
My desk was at the time located on a developer-heavy floor, very silent, with everybody neck-deep into their code. They generally regarded me as "the uninitiated", treating me with contempt, at most. Hardly ever anyone talking to me. Two developers were sitting across my desk and they were smokers, so we occasionally ended up on the balcony together. One day, they were talking about an application UI bug which they were trying to fix. I, as a non-developer, was ignored, of course, but I was shamelessly eavesdropping in the hopes I would learn something from their... um, well, gibberish (of sorts). The UI bug was around some fields not being populated automatically when values were selected in others. Think of it as a chain of picklists with dynamically populated List-Of-Values.
I gathered my strengths and asked them whether it could be the fact that some picklists are populated in the wrong chronological order. They looked at me in a weird way, said nothing, then thrown their cigarette butts and went inside. I felt like a kid asking "Mooom, what's a dick?" during Uncle Moke's funeral.
Couple hours pass and they come to me and ask me whether I would join them for another cigarette. I was very much surprised. On the balcony, they told me I was actually right and the bug was fixed.
Glad I could help.
They respected me and talked to me a lot more after that, and I helped them crush a few more bugs by just listening to them while they explained what was wrong and brainstorming what might cause it. We still keep in touch even if they moved to a different company.
While the above wall of text is a bit offtopic, the idea is that if a developer treats everyone else as if they are no good, he might miss opportunities.
Lists of bug fixes don't count as documentation (Score:2)
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.
Re: (Score:2)
Big problem: Linux won (Score:5, Insightful)
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.
Some is better than others (Score:2)
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
Re: (Score:2)
The config files have even been moved and no-one bothered to mention that.
I've had to break strace out a few times before to figure out how to even begin configuring some tools, just to figure out where the heck it's trying to read stuff from.
Write some! (Score:3)
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.
Documentation will not fix a bad interface (Score:3)
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.
ARCH LINUX WIKI (Score:5, Informative)
I have found https://wiki.archlinux.org/ [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.
Corrected Title (Score:5, Insightful)
MySQL in particular drives me nuts. (Score:2)
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.
LibreOffice suffers badly from this problem (Score:2)
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 O
How About Crowdfunding? (Score:3)
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.
Rapidly obsolete documentation (Score:3)
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.
I disagree with the premise... (Score:3)
Donate to Gnome's Outreach Program for Women (Score:2)
Use FreeBSD? (Score:2)
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.
Contributors start with documentation (Score:2)
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?
Terrible coding standards (Score:5, Informative)
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.
Re: (Score:3)
Coders are too busy writing code and making changes to what they write to give time for accurate documentation to be written....
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.
You've just described an extremely flawed development model. For some reason you can still get
I don't usually bother (Score:4, Insightful)
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.
Just suffer through it (Score:3)
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.
Writing Manuals and Documentation (Score:4, Informative)
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.
OpenBSD (Score:3)
You must have missed OpenBSD [openbsd.org], then.
I know, I know: It's an exception. I just wanted to mention the best documented Free Software I've ever seen.
I mail the author (Score:4, Interesting)
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 :)
How to fix the sorry state of FOSS docs (Score:4, Interesting)
Hence, "Software Engineer" == MYTH (Score:5, Insightful)
... 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.
Teach, don't tell -- and the non FOSS world. (Score:3, Interesting)
First, I wanted to link to This blog post [stevelosh.com] 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 [wikipedia.org], 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.
Goodbye karma (Score:3)
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.
Re:Read the source code (Score:5, Insightful)
Re: (Score:3)
Re:Read the source code (Score:4, Interesting)
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.
Comment removed (Score:4, Interesting)
Re:Read the source code (Score:5, Insightful)
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.
Re: (Score:3)
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.
Re: (Score:3, Insightful)
Setting up a resource like that doesn't mean that it's filled out in a useful way, and it's not.
Re:Read the source code (Score:4, Insightful)
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.
Yes, proprietary (commercial) often wins here (Score:4, Insightful)
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.)
Re:Read the source code (Score:5, Insightful)
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.
Re:Read the source code (Score:5, Informative)
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.
Re: (Score:3)
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/ [bethsoft.com] where you can get a PDF version, which is slightly over 20 pag
Re: (Score:3)
Isn't "Documentation" a 4-Letter Word?
docx ?
Re:Read the source code (Score:5, Insightful)
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.
Re: (Score:2)
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).
Re: (Score:3, Interesting)
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 document
Re: (Score:3)
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 su
Re: (Score:3)
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.
Re: (Score:3)
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.
Re: (Score:3)
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
Re: (Score:3)
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 bo
Re: (Score:3)
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.
Re: (Score:2)
God I wish I had a million mod points for you.
Re: (Score:3)
That pretty much sums it up, sans all the foul words.
Re: (Score:2)
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).
Re: (Score:2)
True, but it might antagonize other posters. :)
Rarely would a constructive discussion stem from that kind of foul-word-peppered root
At least the neckbeards weren't hipsters. (Score:4, Insightful)
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.
Re: (Score:2)
The neck beards are older. They were like the hipsters when they were in their 20s. Getting older changes things about people. Its a cycle.
Re: (Score:2)
"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.
Hello Grumpynerd? (Score:5, Insightful)
"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... [grumpynerd.com]
Re:Nothing (Score:5, Funny)
MOTHERFUCKER, IT DOESN'T WORK LIKE THAT. Fuck you in your goddamn asshole you fucking arrogant fucking pricks.
Your documentation must have been epic.
Re:Nothing (Score:5, Interesting)
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?
Re: (Score:3)
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.
Re:It's open source (Score:5, Insightful)
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.
Re: (Score:2)
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).
Re:It's open source (Score:4, Interesting)
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.
Re:It's open source (Score:5, Insightful)
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.
Re: (Score:3, Funny)
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?
Re: (Score:3)
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....
Re: (Score:3)
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.
Pers
Re: (Score:3)
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 te