Beta
×

Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

Ask Slashdot: What To Do About the Sorry State of FOSS Documentation?

samzenpus posted about 3 months ago | from the keeping-up-with-the-times dept.

Open Source 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?

Sorry! There are no comments related to the filter you selected.

Read the source code (-1)

Anonymous Coward | about 3 months ago | (#47599775)

I've found the only reliable documentation has been reading the source code itself. I like the doc systems where the developer writes documentation inline with the source code, and it is compiled into separate docs (like Java JavaDocs for example).

Re:Read the source code (5, Insightful)

Anonymous Coward | about 3 months ago | (#47599817)

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.

Re:Read the source code (2)

Pino Grigio (2232472) | about 3 months ago | (#47599899)

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.

Re:Read the source code (4, Interesting)

james_pb (156313) | about 3 months ago | (#47600095)

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.

Yes, proprietary (commercial) often wins here (3, Insightful)

Anonymous Brave Guy (457657) | about 3 months ago | (#47600367)

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 (4, Insightful)

tomhath (637240) | about 3 months ago | (#47599831)

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:Read the source code (1)

suutar (1860506) | about 3 months ago | (#47600089)

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:Read the source code (2)

jellomizer (103300) | about 3 months ago | (#47599935)

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.

Re:Read the source code (2)

Charliemopps (1157495) | about 3 months ago | (#47600217)

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.

Re:Read the source code (2)

SecurityGuy (217807) | about 3 months ago | (#47600013)

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.

Read the source code (0)

Anonymous Coward | about 3 months ago | (#47600201)

I can read the code, read english, write syntactically correct code (sometimes), but write english sentens is somehow difficult. Even more, when it's documentation which should not confuse the reader or when it's on an official wiki where language errors are not very funny :)

*BSD has best-of-breed documentation. (5, Insightful)

Anonymous Coward | about 3 months ago | (#47599781)

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.

Real men (4, Insightful)

Raseri (812266) | about 3 months ago | (#47599807)

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.

Re:Real men (-1)

Anonymous Coward | about 3 months ago | (#47599925)

It's not just open source projects that have this problem, though; plenty of commercial applications also have shit for documentation.

No shit, troll. Nobody said only FOSS projects have shitty documentation. Just that it's a HUGE problem for FOSS. Much more so than with commercial applications.

Re:Real men (4, Insightful)

NotDrWho (3543773) | about 3 months ago | (#47600041)

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:Real men (2)

Raseri (812266) | about 3 months ago | (#47600091)

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.

Re:Real men (0)

Anonymous Coward | about 3 months ago | (#47600227)

Nice. Not only do you fail to answer the points brought up, but you also suggest the OP was in prison based solely on his comment that he wasn't doing hobby computing.

I think "troll" is indeed a valid description of your behavior.

Re:Real men (0)

Anonymous Coward | about 3 months ago | (#47600267)

It's not just open source projects that have this problem, though; plenty of commercial applications also have shit for documentation.

It does not matter. In the sea of commercial garbage software, there's also almost always a premium solution for a problem, which comes with extensive documentation and customer support resources. Then you can just ignore the rest.

It's open source (0)

slashdice (3722985) | about 3 months ago | (#47599811)

fix it yourself.

Re:It's open source (4, Insightful)

war4peace (1628283) | about 3 months ago | (#47599903)

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:It's open source (-1)

Anonymous Coward | about 3 months ago | (#47600017)

Its free, take it or leave it. contribute or STFU.

You don't like it? We don't care.

And the problem isn't ours its yours since you're the one whining.

Re:It's open source (0)

Anonymous Coward | about 3 months ago | (#47600189)

Problem is that in most dev houses, when you spend the time documenting it, the other person who does 10,000 lines a day, but doesn't document, and does not care about bugs, will keep their job, and not you. This is because making a release date with anything is better than code quality or manageability.

Re:It's open source (1)

war4peace (1628283) | about 3 months ago | (#47600231)

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 (0)

Anonymous Coward | about 3 months ago | (#47600233)

A lot of people have programming as a hobby. How many people do you know that likes to write technical documentation as a hobby?
The solution to getting FOSS documentation up to par is to pay someone to do it.

Re:It's open source (-1)

Anonymous Coward | about 3 months ago | (#47599977)

fuck your mother in the cunt.

Re:It's open source (3, Funny)

Anonymous Coward | about 3 months ago | (#47600243)

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?

Ya get what you pay for (1)

bhlowe (1803290) | about 3 months ago | (#47599813)

Hire someone who knows the product (a starving developer?) to help you.

Re:Ya get what you pay for (0)

Anonymous Coward | about 3 months ago | (#47600311)

So, the code is free, but you are suggesting that a developer should be hired to understand the installation options? It's people like you that give open source projects a bad name.

Just avoid shitty GitHub projects. (0, Troll)

Anonymous Coward | about 3 months ago | (#47599823)

The best thing to do is avoid GitHub projects. The GitHub culture is all about spewing out a lot of shitty JavaScript or Ruby code really quickly, making it public using git, then never bothering with real releases or documentation or anything else that's associated with software project management.

Software not hosted on GitHub is almost always a lot better. The fact that it's not hosted at GitHub means that the developers are at least capable enough to set up their own infrastructure, or at least use a hosting platform like SourceForge that encourages real software releases. These developers aren't just about shitting out shitty Ruby or JS code snippets. They're about putting together open source software products, which includes providing regular tested releases and good documentation.

I can't think of the last time I've gone to a project hosted on its own website or even on SourceForge and had a problem finding useful documentation. Sometimes you may need to build from source to get the documentation generated fully, but at least it's there. This is totally the opposite of my GitHub experience, where I often find code with no comments at all, no documentation, and not even a readme file. It has gotten to the point where if a project is hosted at GitHub, I just won't even bother. It likely won't be worth my time trying to deal with its lack of documentation and its horrible source code.

Re:Just avoid shitty GitHub projects. (1)

DaBombDotCom (1587833) | about 3 months ago | (#47599929)

Wow...

Re:Just avoid shitty GitHub projects. (1)

Anonymous Coward | about 3 months ago | (#47600345)

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.

So fix it (2, Interesting)

Anonymous Coward | about 3 months ago | (#47599847)

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:So fix it (1)

butalearner (1235200) | about 3 months ago | (#47600107)

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] .

Nothing (0, Flamebait)

Anonymous Coward | about 3 months ago | (#47599851)

Back when Sourceforge wasn't a shit-heap of garbage in every possible way I did a lot of documentation for various programs. I'm not a programmer at all, but I can use the damn things and tell others how to do so as well. The biggest problems I had were ALWAYS at the hands of the developer. They'd have these posts desperately looking for documentation writers then treat us like total fucking garbage when we had to ask questions. I can't fucking tell you how many times I was told to read the fucking source, despite me being very up-front about my lack of coding ability. "If you can't figure out how to use the program then how can you write documentation?"

MOTHERFUCKER, IT DOESN'T WORK LIKE THAT. Fuck you in your goddamn asshole you fucking arrogant fucking pricks.

I stopped bothering when I stopped using Linux, which is a story in itself. 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. Maybe THEN the people that make documentation will give enough of a shit to try to do so again.

Re:Nothing (1)

NotDrWho (3543773) | about 3 months ago | (#47599901)

God I wish I had a million mod points for you.

Re:Nothing (2)

war4peace (1628283) | about 3 months ago | (#47599923)

That pretty much sums it up, sans all the foul words.

Re:Nothing (1)

Anonymous Coward | about 3 months ago | (#47600117)

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.

Re:Nothing (0)

Anonymous Coward | about 3 months ago | (#47600163)

Au contraire, the foul words make Anon's point very clear and colorful in my opinion.

Re:Nothing (1)

war4peace (1628283) | about 3 months ago | (#47600247)

True, but it might antagonize other posters.
Rarely would a constructive discussion stem from that kind of foul-word-peppered root :)

Re:Nothing (1)

frank_adrian314159 (469671) | about 3 months ago | (#47600241)

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).

At least the neckbeards weren't hipsters. (4, Insightful)

Anonymous Coward | about 3 months ago | (#47600071)

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:At least the neckbeards weren't hipsters. (1)

jbolden (176878) | about 3 months ago | (#47600193)

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:At least the neckbeards weren't hipsters. (0)

Anonymous Coward | about 3 months ago | (#47600331)

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.

So, are you suggesting that hipsters are following in the same path and will die young?
please, oh please say yes

Re:At least the neckbeards weren't hipsters. (1)

Anonymous Coward | about 3 months ago | (#47600263)

I couldn't agree more. With hipsters their coding style is a stab in the dark, they don't know how to debug, how to problem solve, how to design. They just throw random things together and add more spaghetti code, then end up begging for solutions on stackexchange. On some commercial projects I've had unresponsive hipster developers tell me they spent the last N days getting high as if that excused their lack of work. It's a fucking mess, and it really makes me wonder where software development is headed 20-30 years from now if these people don't grow up.

Neckbeards can be trollish and vain, but they can code, they can work, and they do get results. I'd rather take a frustrating neckbeard who does his job than some pothead hipster who produces unmaintainable garbage.

Re:Nothing (1)

Archangel Michael (180766) | about 3 months ago | (#47600081)

"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? (4, Insightful)

MRe_nl (306212) | about 3 months ago | (#47600105)

"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 (0, Insightful)

Anonymous Coward | about 3 months ago | (#47600131)

I'm shocked that no-one wanted to work closely with you.

Re:Nothing (0)

Anonymous Coward | about 3 months ago | (#47600185)

you kiss your mama with that mouth ?

Re:Nothing (4, Funny)

AmiMoJo (196126) | about 3 months ago | (#47600257)

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 (1)

Charliemopps (1157495) | about 3 months ago | (#47600261)

Programmers acted like arrogant jerks? I don't believe it!

Software Documentation is bad everywhere (3, Insightful)

jellomizer (103300) | about 3 months ago | (#47599859)

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 (1)

Anonymous Coward | about 3 months ago | (#47599983)

Nonsense! Professional software uses professional tech authors. I've never had any documentation issues using IBM, Oracle and Microsoft development environments.

Re:Software Documentation is bad everywhere (5, Insightful)

johnwallace123 (1173071) | about 3 months ago | (#47600361)

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:Software Documentation is bad everywhere (3, Insightful)

Ghostworks (991012) | about 3 months ago | (#47600025)

"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:Software Documentation is bad everywhere (1)

gfxguy (98788) | about 3 months ago | (#47600121)

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 out and side effects.

The stories would be end user documentation, the tasks developer documentation. That is, if they were written well and following some decent formatting conventions... but that's the problem right there, it's painful even getting users to properly describe the problems they are trying to solve, let alone developers providing *doc type descriptions in their tasks.

Re:Software Documentation is bad everywhere (2)

jbolden (176878) | about 3 months ago | (#47600221)

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 user wants:

Story: How to enter a transaction

Re:Software Documentation is bad everywhere (2)

Captain Hook (923766) | about 3 months ago | (#47600287)

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 domain.

There is a big gap between User Story and implementation specific documentation.

Re:Software Documentation is bad everywhere (1)

Livius (318358) | about 3 months ago | (#47600031)

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:Software Documentation is bad everywhere (1)

Archangel Michael (180766) | about 3 months ago | (#47600139)

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 (4, Informative)

dskoll (99328) | about 3 months ago | (#47600209)

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.

A Wiki is not Documentation!!! (2, Interesting)

Anonymous Coward | about 3 months ago | (#47599861)

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.

Re:A Wiki is not Documentation!!! (0)

Anonymous Coward | about 3 months ago | (#47600303)

Man pages only make sense for command-line apps. But the UX designers have crapped all over FOSS, and we will never have good documentation again.

Yes! (5, Interesting)

war4peace (1628283) | about 3 months ago | (#47599881)

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:Yes! (1)

serviscope_minor (664417) | about 3 months ago | (#47600083)

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:Yes! (1)

gfxguy (98788) | about 3 months ago | (#47600169)

Where've you been looking? The Ubuntu forums are generally not bad at all, and in my experience have been very user friendly. I've been using Linux for quite some time; I'm a developer, but don't think everybody should have to be a system administrator in order to use Linux as their desktop. I don't know everything... I write graphics applications. If my network or sound card isn't working, I have just as much of a problem as most newbies.

Lists of bug fixes don't count as documentation (1)

NotDrWho (3543773) | about 3 months ago | (#47599887)

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:Lists of bug fixes don't count as documentation (1)

gfxguy (98788) | about 3 months ago | (#47600177)

That's a nice sentiment, but not always practical for FOSS development.

I don't (0)

Anonymous Coward | about 3 months ago | (#47599891)

If all a Google search does is turn up the millions of listserv mirror sites (why do these exist) where someone, somewhere made a comment about the issue, then the time has come to drop the subject, and the project. It's not worth the time or frustration.

Big problem: Linux won (4, Insightful)

Dimwit (36756) | about 3 months ago | (#47599913)

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.

Re:Big problem: Linux won (0)

Anonymous Coward | about 3 months ago | (#47600207)

I love how the *roff manuals are huge, packed with stuff, but no relevant information. Lots of history, you get to learn everything about the author's life, but in the end you still don't know the first thing about using *roff.

Re:Big problem: Linux won (0)

Anonymous Coward | about 3 months ago | (#47600293)

How many people today even know what groff/troff/tbl/pic are?

Some is better than others (1)

willoughby (1367773) | about 3 months ago | (#47599915)

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.

Re:Some is better than others (1)

serviscope_minor (664417) | about 3 months ago | (#47600191)

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.

Because (0)

Anonymous Coward | about 3 months ago | (#47599927)

Writing the documentation means having to both understand the code, and be able to get laymen level detail across to a wider audience. And to do all of this usually for little or nothing. Its not in the artistic end of a coders spectrum where he is trying to create, andthe really smart people will figure shit out themelves. You have a point. Core, solid documentation used to be part of computing, if you really wanted to do something or get anywhere, your program / system would have to come with solid documentation.

Does anyone think Unix would have worked if MAN pages had not been around (I'm being very general - I know..)

On the other hand, I see lots of projects asking people to step forward and help, including the none coding parts. And it underlines that many things don't just exist on coding leet skills. If you have a project and want it to progress, Its an area that would require some attention. How much is variable.

Re:Because (1)

jbolden (176878) | about 3 months ago | (#47600249)

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.

Write some! (2)

DarkOx (621550) | about 3 months ago | (#47599981)

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.

The ArchWiki is salvation (1)

Skarjak (3492305) | about 3 months ago | (#47599997)

The wiki for Archlinux [archlinux.org] 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.

ARCH LINUX WIKI (4, Informative)

hduff (570443) | about 3 months ago | (#47599999)

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 (4, Insightful)

harl (84412) | about 3 months ago | (#47600015)

Ask Slashdot: What To Do About the Sorry State of All Software Documentation Everywhere?

Doctor, it hurts when I eat chicken... (-1)

Anonymous Coward | about 3 months ago | (#47600019)

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.

Re:Doctor, it hurts when I eat chicken... (0)

Anonymous Coward | about 3 months ago | (#47600181)

In addition to missing documentation, there is often also bugs and unimplemented features.

Since this is equally true of proprietary software, you seem to have no workable advice to offer.

MySQL in particular drives me nuts. (1)

SecurityGuy (217807) | about 3 months ago | (#47600039)

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 (1)

uncqual (836337) | about 3 months ago | (#47600063)

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.

Not an open source problem (1)

Anonymous Coward | about 3 months ago | (#47600111)

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?

Step 1: Stop ignoring tech writers offering help (0)

Anonymous Coward | about 3 months ago | (#47600133)

I'm a tech writer who has offered to help with various projects. E-mails get ignored. Support tickets get pushed to infinity. Threads get one post saying 'yeah, good idea' and yet no further action gets taken.

Oh, of COURSE you believe in good documentation.

How About Crowdfunding? (2)

Bob9113 (14996) | about 3 months ago | (#47600141)

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.

Free stuff doesn't necessarily mean it's good (0)

DidgetMaster (2739009) | about 3 months ago | (#47600153)

Free software is....well...free. The people who wrote it don't get paid. That means they generally only want to do the "fun stuff". In my experience as a programmer, all the grunt work (error checking, documentation, well formed error messages, etc.) is generally avoided by coders until the company says "you have to do X, Y, and Z before we can ship this product and customers will pay for it. You do it because you are paid to do it. FOSS software has no such motivations so all the "not fun" stuff goes largely undone. Some free software is great. A bunch of it is garbage. Without a profit motive, why should anyone be surprised that most of it is half-baked at best.

Use open source software on Windows (0)

Anonymous Coward | about 3 months ago | (#47600187)

It just works and it's well documented. I've tried Linux many times and always gave up. All my Windows software (other than the OS) is free software, and I couldn't be happier.

I disagree with the premise... (2)

QuietLagoon (813062) | about 3 months ago | (#47600195)

The state of FOSS documentation is about the same or, in my experience, a bit better, than the state of software documentation in general.

Donate to Gnome's Outreach Program for Women (1)

twistedcubic (577194) | about 3 months ago | (#47600203)

Because they include documentation as one of their priorities.

Use FreeBSD? (1)

ogdenk (712300) | about 3 months ago | (#47600211)

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.

semi-colons (0)

Anonymous Coward | about 3 months ago | (#47600223)

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.

It's probably best to use semi-colons rather than commas in this.

Contributors start with documentation (1)

MobyDisk (75490) | about 3 months ago | (#47600235)

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?

Report missing/wrong documentation as a bug (1)

MobyDisk (75490) | about 3 months ago | (#47600255)

Do any F/OSS projects allow you to report bugs in the documentation using the bug reporting tool?

/usr/share/doc (1)

twistedcubic (577194) | about 3 months ago | (#47600285)

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.

If its as sorry as you say (0)

Stumbles (602007) | about 3 months ago | (#47600309)

then quit your bellyaching and fix it whiner. Its not like they use closed source proprietary nebulous document formats. Slashdot articles have gone into the toilet.

I just let time sort it out for me (0)

Anonymous Coward | about 3 months ago | (#47600317)

I work on several open source projects. What I do is first get hacker-types (the people who like to take things apart, investigate further, research and learn, the traditional meaning of the word) hyped up over the project, giving it some tech cred. Then I tell reddit that my projects are awesome and point to the tech cred as evidence.

This step is important. Reddit, and similar other community-moderated fourms, are all about gaining internet points. Once those forums are secured, Stackoverflow will eventually fill up with questions and answers pertaining to my projects, and voila, documentation written.

Try FreeBSD (0)

Anonymous Coward | about 3 months ago | (#47600329)

Back when I was a wee nipper, I remember having to learn how to consult and search man pages in order to run GNU/Linux. I've found that FreeBSD's documentation is generally excellent. Maybe it's something about BSD culture, but I find that it's where idiots like myself that need good docs have gravitated.

Google it (0, Insightful)

Anonymous Coward | about 3 months ago | (#47600341)

A simple search on Google will find what you need If it isn't in the man page.

Terrible coding standards (4, Informative)

Enry (630) | about 3 months ago | (#47600369)

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.

Load More Comments
Slashdot Login

Need an Account?

Forgot your password?