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!

WTFM: Write the Freaking Manual

timothy posted about 2 years ago | from the so-to-speak dept.

Books 299

theodp writes "Blogger Floopsy complains that he would love to RTFM, but can't do so if no one will WTFM. 'You spend hours, days, months, perhaps years refining your masterpiece,' Floopsy laments to creators of otherwise excellent programming language, framework, and projects. 'It is an expression of your life's work, heart and soul. Why, then, would you shortchange yourself by providing poor or no documentation for the rest of us?' One problem with new program languages, a wise CS instructor of mine noted in the early look-Ma-no-documentation days of C++, is that their creators are not typically professional writers and shy away from the effort it takes to produce even less-than-satisfactory manuals. But without these early efforts, he explained, the language or technology may never gain enough traction for the Big Dogs like O'Reilly to come in and write the professional-caliber books that are necessary for truly widespread adoption. So, how important is quality documentation to you as a creator or potential user of new technologies? And how useful do you find the documentation that tech giants like Google (Go), Twitter (Bootstrap), Facebook (iOS 6 Facebook Integration), Microsoft (Windows Store apps), and Apple (Create Apps for IOS 6) produce to promote their nascent technologies? Is it useful on its own, or do you have to turn to other 'store-bought' documentation to really understand how to get things done?"

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

i wrote the manual (-1)

Anonymous Coward | about 2 years ago | (#41508415)

on frosty piss.

Writing documentation is boring and tedious. (-1, Troll)

Anonymous Coward | about 2 years ago | (#41508419)

'Nuff said.

and what does the kama sutra have to do with this? (3, Interesting)

RobertLTux (260313) | about 2 years ago | (#41508433)

Whenever i get a response of RTFM most of the time its either
1 WTFM first (or update it with the new changes)

2 The Kama Sutra covers the subject better

Challenge for the SlashMind locate a current (2.6*) copy of the Blender manual in PDF format.

Re:and what does the kama sutra have to do with th (0)

Anonymous Coward | about 2 years ago | (#41508479)

Meh, at least the 2.6 manual is up on the wiki. Though... it's not done yet.

Re:and what does the kama sutra have to do with th (-1)

Anonymous Coward | about 2 years ago | (#41508675)

Oh stop being cheap and just buy a copy of Cinema 4D. Blender is ass.

Examples (4, Insightful)

tomhath (637240) | about 2 years ago | (#41508439)

First provide some *working* examples. Then some real documentation (not Java Docs).

Re:Examples (4, Insightful)

Gorath99 (746654) | about 2 years ago | (#41508823)

And then keep both the examples and docs up to date, for god's sake! The only thing worse than no documentation is useless documentation.

Re:Examples (1)

Anonymous Coward | about 2 years ago | (#41508863)

Depending on what you want to do, JavaDoc can be the best way to give documentation. For example, the Java standard library Pattern class is well documented and gives a good overview of the whole regular expression implementation. More complicated things require higher level documentation, though. Javadoc is almost useless or even harmful when trying to create a user interface, and other documentation on the subject is either not too good or not easy to find.

And giving JavaDoc to those who don't use the API but instead use the end program is obviously a bad way to do documentation.

Re:Examples (4, Insightful)

cheesybagel (670288) | about 2 years ago | (#41508925)

Actually if it is an API we are talking about Javadocs work great. Examples are also nice. Real documentation? If the API cannot be understood just by reading the Javadocs then You Are Doing It Wrong! The API sucks.

Re:Examples (0)

Anonymous Coward | about 2 years ago | (#41509089)

First provide some unit tests and regression tests that run under continuous integration. Then some real documentation (not Java Docs).

FTFY.

Smart people don't read the manual anyway (0)

Anonymous Coward | about 2 years ago | (#41508447)

Besides, with GUI or AJAX interfaces applications no longer need manuals. I remember having a shelf of computer books next to my computer desk. both the shelf and desk are gone.

Re:Smart people don't read the manual anyway (1)

Alain Williams (2972) | about 2 years ago | (#41508881)

Not everything is an application that is ''obvious'' to use. If you are writing that AJAX application you need to know how to call the JQuery (or whatever) functions that do the work; for that you need a manual. I agree with Floopsy, a lot of FLOSS is let down by poor documentation, the programmer gets the job done and often has not got the interest to write documentation. The meme ''read the code'' is not always a good one, especially if the code has few comments or just says ''how'' rather than ''why''. Also you might understand individual components but the intention of how it is to be used is not always easy to deduce. The best guy to write this sort of thing is the designer who, in many FLOSS projects, is the guy who writes the code. With stuff that I do, I often find that writing the documentation can take about the same sort of time that it takes to write the code.

Even if you are talking about an application with a GUI, you may need a manual for obscure or complex things, eg: exporting data and importing it to somewhere else.

Re:Smart people don't read the manual anyway (2)

rs79 (71822) | about 2 years ago | (#41509121)

" The meme ''read the code'' is not always a good one, especially if the code has few comments or just says ''how'' rather than ''why''."

"Comments lie. Code never lies" - Keith Doyle

In addition... (5, Informative)

Anonymous Coward | about 2 years ago | (#41508455)

to WTFM, please oh please oh please stop writing flowery, circumlocutious prose.

Succinct... Precise... Concise...

Bullet points, short paragraphs, and simple descriptions are fine in most circumstances; this is not an expository writing project. I don't want to have to wade through your awful prose to decipher what the hell you're trying to say.

If I want to read a fucking story, I'll read a novel.

Documentation? (5, Funny)

fahrbot-bot (874524) | about 2 years ago | (#41508459)

Real programmers don't document. If it was hard to write, it should be hard to understand. :-)
You youngsters always want things "explained" - geesh.

Seriously, get your hands dirty and work for it.

Re:Documentation? (1)

Anonymous Coward | about 2 years ago | (#41508603)

It's you youngsters who aren't writing the documentation. The reason "RTFM" is a thing we old geezers say is because we actually write TFM in the first place.

Re:Documentation? (1)

Anonymous Coward | about 2 years ago | (#41508819)

There have been a few free software and/or open source software projects that I would have joined as a programmer except there was no usable documentation about the software. A couple programming examples and an overview of the "architecture" is NOT documentation. I would have written the documentation if I could identify any structural coherence to the source code. Write the damn documentation first, then write the code, then revise the documentation as each portion of the code is finalized.

Re:Documentation? (1)

Anonymous Coward | about 2 years ago | (#41508725)

Goto Hades :Hades Goto Heck :Heck Goto top

Re:Documentation? (1)

SailorSpork (1080153) | about 2 years ago | (#41508849)

Funny with a touch of truth, but it doesn't work so well in the world of multiple platforms and languages competing with each other for adoption. For instance, if am am the manger of a company writing a mobile app, and the iOS manual is clean and easy to read with no issue, and the Android manual is cryptic and would take gobs of trial & error to get working, iOS is language is the platform the app will be written for first and best, and we'll get around to the Android one later, if at all. I'm not saying the above example is true, just using it for sake of hypothetical example. Not everyone's manger has the patience to let you learn nuances of each language and platform. The manual almost needs as much effort and attention as the marketing materials, and probably more.

Re:Documentation? (1)

cheesybagel (670288) | about 2 years ago | (#41508939)

I'll trade the supposed mess of learning Android which is mostly plain standard Java with its own UI and mobile specific APIs to learning Objective-C and a whole enchilada of Apple designed APIs which are not used anywhere else thanks.

Re:Documentation? (0)

Anonymous Coward | about 2 years ago | (#41508877)

While this kind of mentality DOES have it's merits, as there is no way to learn but actually DOING it, there's a limit as to how far it should be taken.

i.e.: the way people are responded to when they ask for help from the linux community. When others become elitist towards the new folk, that's when it's gone too far.

Documentation can make a standrd (5, Insightful)

xtal (49134) | about 2 years ago | (#41508461)

I consider it no accident that the defacto standard language C (aka, "portable assembler") has a lot to do with not only it being the language of choice for UNIX, but the fact that it was accompanied by one of the masterpieces of programming documentation - "The C Programming Language" - By K&R, who most know also designed and developed the language itself.

Your ideas are no good if they can't be communicated to others. Often, inability to communicate good ideas is more an indicator the ideas aren't that good, than the documentation is lacking.

Re:Documentation can make a standrd (0)

Mormz (1690440) | about 2 years ago | (#41508621)

Just the example I was going to use. When I was in elementary I borrowed the first edition of K&R from dad's colleague. It's still sitting on my shelf. It's still relevant, and it taught me C. It's the standard on C, been standardised by ANSI, and I'm really considering buying a new one.

Relatively small book, about 300 pages, but it tells you everything you need to know to write C. Everything. When writing docs for my own software I always use this book as a guide. Small, short and to the point. Don't shy away from explaining the implementation, but don't skip on the part how to use it also.

Also Douglas Crockford's, Javascript - The Good Parts, which is also a great book. And Demistified C++ from Kent is also very good (half of my country developer workforce literally learnt C++ based on that book). On the broad coverage scale, Java - The Complete Reference. Both as a murder weapon (1000+ pages), and in the detail of showing various features and quirks of the language and the platform.

And yeah, there was this great book about Pascal I read as a teenager, but I hated programming in Pascal (since I did a lot of C back then), so I forgot the author of the book :( Book was great, the language was not.

Re:Documentation can make a standrd (5, Funny)

Anonymous Coward | about 2 years ago | (#41508861)

When I was in elementary I borrowed the first edition of K&R from dad's colleague. It's still sitting on my shelf.

It's your dad's colleague here, and I'm still waiting for you to return my damn book!. Kids these days, no respect.

Re:Documentation can make a standrd (0)

Anonymous Coward | about 2 years ago | (#41508623)

Point of information (via Wikipedia):

Kernighan has said that he had no part in the design of the C language ("it's entirely Dennis Ritchie's work").

Re:Documentation can make a standrd (1)

cheesybagel (670288) | about 2 years ago | (#41508945)

Nah he just designed AWK and helped design UTF-8.

Re:Documentation can make a standrd (1)

cheesybagel (670288) | about 2 years ago | (#41508959)

Oops UTF-8 was Ken Thompson and Rob Pike. Oh well AWK it is.

Re:Documentation can make a standrd (3, Interesting)

znigelz (2005916) | about 2 years ago | (#41508657)

I second this post. K&R is the evolution of the C specification, and some versions of C compilers were written entirely from the book itself. C++ was developed in 1979, but not released to the public until 1983 (the year I was born, coincidence? I think not). Bjarne Stroustrup worked for Bell labs. Bell kept the official documentation, "The C++ Programming Language", under wraps until 1985. Wow, two whole years (though I'm sure too long for some of your old wizards). It is without question the best meta/template programming manual ever written.

inability to communicate good ideas is more an indicator the ideas aren't that good

If you find his book too complicated, then check out Stroustrup's other book, "Programming Principles and Practice using C++", which is more like a high school text book. Or check out his amazing and simplistic site for the aggregation of information crucial to c++, http://www.stroustrup.com/C++.html [stroustrup.com]

He may not be the greatest writer, or the most congenial, but his ideas were great, and no one can argue against it. No language is as dominant and most crucial to the world's infrastructure, and his books (and his online material) are a great companion in your time of need.

Re:Documentation can make a standrd (1, Troll)

cheesybagel (670288) | about 2 years ago | (#41508975)

If you want something simple you don't program in C++. It's a convoluted mess of a language so of course no amount of documentation is going to solve that problem. Unfortunately there are little choices (except C of course) if you want to write reasonably portable high performance code.

Re:Documentation can make a standrd (2)

robthebloke (1308483) | about 2 years ago | (#41509175)

but his ideas were great, and no one can argue against it.

There are plenty of people who can argue against the design choices in C++, and plenty of people who think his ideas don't translate very well into large scale maintainable systems. He's made a huge computer to computer science, but that does not mean he hasn't made a few mistakes along the way.

No language is as dominant and most crucial to the world's infrastructure

Only if you are one of those people who refuse to acknoweldge the existence of C.

Re:Documentation can make a standrd (2)

blade8086 (183911) | about 2 years ago | (#41508967)

Not to mention that UNIX's 1st 'official' funding at bell labs was to develop TYPESETTING applications for DOCUMENTS

(see nroff - which is used to render man pages.. aka TFM of RTFM on a unix system)

The fucking manual (0)

Anonymous Coward | about 2 years ago | (#41508463)

I'm pretty sure it's never been "freaking" unless you're one of those awkward persons who are in the mid-ground between wearing a tie and wearing sandals to work.

If it ain't in writing (4, Insightful)

k6mfw (1182893) | about 2 years ago | (#41508481)

it doesn't exist. OK so a bad tagline but I've encountered so many devices, systems, etc. with no documentation. Now I can understand if someone throws together a contraption late at night, then have a few hours sleep, next morning they move on to their next gadget. However, I have little tolerance of people bragging of how great their thing is, everyone else's systems are inferior, etc, etc, etc but they have no paperwork. Or else they have tons and tons (but in PDF format to not cut down a huge forest) which basically is same as none existance because you will be dead of old age by the time you get through all that material. If they don't have much documentation then be honest about it. There are a lot of smart people that design and build neat stuff, their strengths are not in well written documents. That's when you bring in applications engineers and tech writers.

Re:If it ain't in writing (1)

fm6 (162816) | about 2 years ago | (#41508809)

It's a perfectly good tagline, one I've used myself many times. Though to be consistent,you should say "it don't exist".

WTFC? (-1, Troll)

gelfling (6534) | about 2 years ago | (#41508483)

Who the fuck cares? In my company we grind out 40 page outlines on the template for writing a document everyday. Any document that's 30 pages long, once you strip out the cover page, change history, authors, approvers, ToC and glossary it's 8 pages. And 4 of them are textual repeats of the flowcharts on the other 4 pages.

A manual? Dear lord, any manual more than 5 pages long no one will ever read and any manual less than 5 pages long, is irrelevant make work.

Linux users targeted by 'Wirenet' Trojan (-1)

Anonymous Coward | about 2 years ago | (#41508495)

-=-
Linux users targeted by password-stealing 'Wirenet' Trojan

Open source gets some attention

By John E Dunn | Techworld | Published: 12:58, 31 August 2012

http://news.techworld.com/security/3378804/linux-users-targeted-by-password-stealing-wirenet-trojan/ [techworld.com]
-=-
"Malware writers are interested in Linux after all. Russian security firm Dr Web has reported[1] finding a shadowy Trojan that sets out to steal passwords on the open source platform as well as OS X.

Technical details of Wirenet.1â(TM)s operation and technique for spreading are sparse for now, but the company reports that the backdoor program targets browser passwords for Opera, Firefox, Chrome, Chromium, and as well as applications such as Thunderbird, SeaMonkey, Pidgin.

Under Linux it copies itself to the ~ / WIFIADAPT directory before attempting to connect to a command and control server hosted at 212.7.208.65 using an AES encrypted channel. That at least offers a simple way of blocking communication and any further payloads.

Dr Web made a name for itself earlier this year reporting on the infamous Flashback Trojan[2] that hit Mac users on an unprecedented scale.

Itâ(TM)s not clear whether Wirenetâ(TM)s cross-platform capabilities extend to targeting Windows systems but it is possible that avoiding Microsoftâ(TM)s OS is a way of keeping off the radar of security firms.

Cross platform malware is rare but not unheard of, the usual technique being to hook into Java in search of victims using OS X.

Malware specifically designed to steal credentials from Linux systems is almost unheard of but might, on the basis of this new discovery, become a little less so in future.

Should Linux users be worried? Probably not. the details of how this malware might grab root mode on a Linux system are unknown. Atacking Linux users would also be a pretty rarified activity unless it was part of a highly-targeted attack.

"We do not have explicit evidence that it uses Java. To my knowledge it does not. This file was received from Virustotal," Dr Web analyst Igor Zdobnov told Techworld."

[1] http://news.drweb.com/show/?i=2679&lng=en&c=14 [drweb.com]
[2] http://news.techworld.com/security/3353152/flashback-trojan-still-on-650000-macs-security-company-discovers/ [techworld.com]
-=-

good docs make a big difference (0)

Anonymous Coward | about 2 years ago | (#41508505)

In making a decision on whether or not to use a technology or one from a number of competing technologies, one criteria I use is does it have documentation and how good is it? In a professional environment where speed is important because of deadlines and budgets, not having good docs (which forces me to poke and prod myself to figure out what's going on) is a big negative. I find PHP to have top of the line documentation, Microsoft and MySQL above average but occasionally confusing or less than relevant documentation. Google is also uneven - sometimes it's very helpful, sometimes it's so convoluted that I spend hours just trying to figure what the they're talking about. Just my 2 cents.

Oh, crap, it's a wiki (5, Insightful)

Animats (122034) | about 2 years ago | (#41508509)

I once tried Inkscape and realized in disgust that the "manual" was a wiki.

When I was working in aerospace, we would often write the manual first, then implement. This forces developers to deal with ugly problems cleanly, rather than having some elaborate after-the-fact explanation of how to work around some limitation.

Re:Oh, crap, it's a wiki (5, Interesting)

menno_h (2670089) | about 2 years ago | (#41508573)

When I was working in aerospace, we would often write the manual first, then implement. This forces developers to deal with ugly problems cleanly, rather than having some elaborate after-the-fact explanation of how to work around some limitation.

Also, this gives you a design plan that you can follow while coding.

Re:Oh, crap, it's a wiki (2)

Hentes (2461350) | about 2 years ago | (#41508723)

The problem is not when it's a wiki, but when there are only like 3 articles in it.

Re:Oh, crap, it's a wiki (1)

fm6 (162816) | about 2 years ago | (#41508825)

As a tech writer, I've been fighting a losing battle against the wiki-docs approach for years. Nobody seems to grasp that Wikis undo a couple decades of progress in writing well-structured, process-driven docs. Confluence even pushes its own wiki as docs tool. Needless to say, documentation is the weak point in Confluence's otherwise excellent products.

The design-by-document approach just isn't going to fly in this age of minimalist organization and agile development.

Re:Oh, crap, it's a wiki (3, Insightful)

cheesybagel (670288) | about 2 years ago | (#41508985)

Wiki documentation can be great if the people editing the wiki aren't a bunch of morons. Make of that what you will.

Re:Oh, crap, it's a wiki (2)

mdfst13 (664665) | about 2 years ago | (#41509153)

The design-by-document approach just isn't going to fly in this age of minimalist organization and agile development.

There is no reason why you can't write the documents first in agile development. You just can't finish the documentation before starting coding. You can write documentation of the next set of code to be written before writing it. Agile mixes well with extreme, test first programming. Do the documentation the same way. Write a bit of documentation; write the tests that match it; write the code to make the tests work. Repeat until finished. At that time, you will have complete documentation, a test suite, and working code.

The big difference between agile and waterfall is that agile is more incremental based. Good agile development follows the same steps as good waterfall. It just processes them in smaller chunks.

The good thing about agile development is that it is adaptive. The bad thing about agile is that you don't know what the final product will be until you are finished. Whether it works for your circumstances depends on whether it is more important to know the specifications of the final product early or to adapt to changing circumstances.

Re:Oh, crap, it's a wiki (1)

cheesybagel (670288) | about 2 years ago | (#41508997)

That is a great idea assuming you already know how your solution is supposed to work and behave within the boundaries of available resources. In which case you probably already did the application before. If you already did the application before why are you coding it again? Copying your own code isn't exactly hard.

Re:Oh, crap, it's a wiki (3, Informative)

Tsu Dho Nimh (663417) | about 2 years ago | (#41509103)

When I was working in aerospace, we would often write the manual first, then implement. This forces developers to deal with ugly problems cleanly, rather than having some elaborate after-the-fact explanation of how to work around some limitation.

I used to get paid to WTFMs. If there was a good functional specification for the hardware or software, I could have the first draft done about the same time the early testing started, and much of it was lifted from the specs. You don't have to see it working to describe what it is supposed to do.

If I had to WTFM for something with a bad spec or no spec, something that was being developed ad hoc ... it took a lot longer.

Great but (-1)

Anonymous Coward | about 2 years ago | (#41508513)

When will Apple write a manual for their damned devices?

Re:Great but (4, Informative)

jo_ham (604554) | about 2 years ago | (#41508741)

When will Apple write a manual for their damned devices?

What do you mean? Apple write manuals for their devices. They are available in PDF form on their website. They don't print the full manual and include it in the box any more to save on waste, instead just giving a brief quickstart guide, but the full manuals are still available. They are also available in iBooks.

Here's the (156 page) iPhone 5 manual, for example: http://manuals.info.apple.com/en_US/iphone_user_guide.pdf [apple.com]

Re:Great but (0)

Anonymous Coward | about 2 years ago | (#41508753)

Thank you. No, seriously. There wasn't even any notification on the device or the in the box to let me know that.

Re:Great but (0)

cheesybagel (670288) | about 2 years ago | (#41509005)

To save waste? More like to increase profit.

Re:Great but (1)

jo_ham (604554) | about 2 years ago | (#41509187)

To save waste? More like to increase profit.

Ah, yes, sorry I forgot to engage my ultra-cynical "all companies have a Machiavellian conspiracy going on" mode before posting. *eyeroll*

More than a few assumptions here (2)

Kjella (173770) | about 2 years ago | (#41508519)

The first assumption is that you're actually writing it for somebody else and not yourself. In many cases if you've scratched your own itch, then you're happy and any comments are notes to self, not documentation for others. The second assumption is that you could, that it's only a lack of willpower. To many people coding a piece of software makes the logic of it so apparently obvious that they don't understand why it needs documentation, at least not any that's useful to anyone with a black box understanding of the code. The third assumption is that they're not once bitten, twice shy from useless or even misleading documentation and just decided that the code is the ultimate truth of what the code does and don't want to make any external document that won't stay in sync.

Re:More than a few assumptions here (1)

Anonymous Coward | about 2 years ago | (#41508755)

1) If your software has been released to the public (i.e. because you released it to the public) the assumption is that you want others to use it. Elsewise, keep it on your hard drive and stop polluting sourceforge. Too many people it seems have the mentality that they can just share their own dog food and others will want to lick the bowl. The thought process is basically "well, I can't sell this, but if I just give it away, maybe it'll make me famous and lead to something big." It's just a really lazy form of greed and opportunism, and thank goodness it doesn't work.

2) As you alluded to, you're not writing the docs for yourself. Nobody else cares how elegant your code is, if they're borrowing your stuff that means they just want to use your function and don't want to read your code. If your docs don't clearly explain what the function does, what arguments to pass, and what can be returned, then no matter how elegant your code might be, it's undocumented for the purposes of anyone who is looking for documentation.

3) People who are not interested in documentation aren't the subject of the article.

Yes, these are all assumptions, reasonable ones given the context of the article. If you're not interested in docs, good for you, move along, the article does not apply to you as a reader of docs, only as a producer of code that nobody else wants to use.

Re:More than a few assumptions here (2)

Kjella (173770) | about 2 years ago | (#41508851)

1) If your software has been released to the public (i.e. because you released it to the public) the assumption is that you want others to use it. Elsewise, keep it on your hard drive and stop polluting sourceforge. Too many people it seems have the mentality that they can just share their own dog food and others will want to lick the bowl. The thought process is basically "well, I can't sell this, but if I just give it away, maybe it'll make me famous and lead to something big." It's just a really lazy form of greed and opportunism, and thank goodness it doesn't work.

By writing the code you've done all the work and throwing it out there costs nothing, in case someone finds it useful. Nothing more was implied nor guaranteed, did a rotten piece of source code you got from Sourceforge steal your girlfriend or run over your dog or something?

If you're not interested in docs, good for you, move along, the article does not apply to you as a reader of docs, only as a producer of code that nobody else wants to use.

Fair enough, if you're sure it's the documentation and not an awkward interface to poor code - I'd probably keep working on those two. Well working interfaces calling good code gets used, while a turd is still a turd even if you document it.

Documentation is just large form comments. (5, Insightful)

Anonymous Coward | about 2 years ago | (#41508525)

I've met quite a few coders who are disdainful of documentation, citing many of the reasons that coders give for being disdainful of comments. - It gets out of date quickly, there's a good chance it doesn't match the actual behavior, etc. "If I want to know what's going on, I have to read the code anyway, so what's the point?" There's also a very slight alpha-hacker subtext, with the philosophy of "if you can't read code, you're not worthy enough to be using this program in the first place". As well as the "works for me" viewpoint - the coder who wrote it doesn't need any documentation to understand it, so why is it necessary?

It's sometimes difficult to convince a coder that there are people out there who are competent, intelligent, successful people but who have no interest in plowing through 1000+ lines of code in order to find out which flag they should use to get .png output. To someone who gets a frisson of pleasure at deciphering a wall of obfuscated Perl, it's a foreign concept that there are people out there that have other things they'd rather be doing.

 

Re:Documentation is just large form comments. (3, Insightful)

vlm (69642) | about 2 years ago | (#41508669)

There's also a very slight alpha-hacker subtext, with the philosophy of "if you can't read code, you're not worthy enough to be using this program in the first place"

Also the alpha hacker view of my code is like poetry, perfect, precise, crystal clear, and self documenting. Usually... not.

Re:Documentation is just large form comments. (1)

cheesybagel (670288) | about 2 years ago | (#41509021)

To me it only makes sense to start writing the documentation once the codebase has reached a certain degree of maturity. If you are constantly refactoring and recoding everything all the time, like in the beginning of any project, documentation is just a plain waste of time.

The manual should come from the specifications... (0)

Anonymous Coward | about 2 years ago | (#41508531)

If it is a language, then the minimal documentation is a reference manual - which comes out of the specifications. Syntax diagrams, with minimal examples of correct expressions. This document is not that hard to write, as long as the "developer" writes down what he is trying to do to meet the project specifications.

Without specifications, you don't know if there is an error or not... or even if the developer knows what he is doing.

The reference manual provides guidance on USING the language, though it may not say HOW to solve problems.

That is up to a different document, the reference guide - which includes small examples to illustrate various topics. THIS manual is much harder to write, as it usually requires some experience with the language to have something to make examples from.

Re:The manual should come from the specifications. (2)

cheesybagel (670288) | about 2 years ago | (#41509031)

You are assuming the specifications make sense or are actually what the client wants which isn't necessarily the case.

WTFM? (2)

russotto (537200) | about 2 years ago | (#41508571)

I wrote the fine code, YOU write the fine manual. Do I look like a tech writer? No, I do not. (They generally dress better but are more disheveled, which may have to do with the contents of their hip flask)

Re:WTFM? (1)

Anonymous Coward | about 2 years ago | (#41508617)

If you rely on others to document your code, then your code probably stinks like fresh skunk roadkill. You learn a lot about how terrible your code is by trying to document it.

Re:WTFM? (2)

fm6 (162816) | about 2 years ago | (#41508891)

Fine, I'll write your manual for you. Shall we discuss money?

What, no money for docs? Never mind!

Re:WTFM? (2)

rs79 (71822) | about 2 years ago | (#41509183)

Tell you what, write the manual and get a 90% refund on the price of the free software you're using.

Get a tech writer buddy (5, Insightful)

sandytaru (1158959) | about 2 years ago | (#41508607)

Former English and journalism majors, who are not always the best programmers but are very very good at explaining how a program works (or ought to work), should be inside every IT company and department on the planet. When I'm not monitoring servers (e.g. watching paint dry), which is my formal job description, I'm writing down everything from internal business processes to how-to installation guides on software for specific networks. My happy place is about fifty pages deep in a Word file.

Re:Get a tech writer buddy (0)

Anonymous Coward | about 2 years ago | (#41508869)

My happy place is about fifty pages deep in a Word file.

You'd be in nirvana if you wrote the systems documentation using LaTeX. And you might even find "your happy place." ;)

Re:Get a tech writer buddy (4, Insightful)

fm6 (162816) | about 2 years ago | (#41508879)

I'm appreciative of your positive comments about my profession, but you overstate the contribution of English and journalism types. There are indeed many good tech writers with that background, but there are also English types who drift into it because they can't get work doing anything else, and produce cruddy docs based on too-fancy prose styles and lack of serious interest in technology.

Many good technical writers have technical backgrounds. I myself am a college dropout who wanted to be a computer scientist but didn't have the intellectual chops for it. Others I've known have been retooled scientists, humanities professors, and MBA types. The one constant is that you need the ability to explain complicated ideas simply (for which traditional training in writing doesn't always prepare you), a certain amount of simple curiousity, and the ability to ask the right "stupid" questions.

BTW, anybody needs some APIs documented? User manuals? Installations guides? I get off my current assignment in about a month, If you have an interesing open-source project, I will consider donating some of my time.

Re:Get a tech writer buddy (3, Interesting)

sandytaru (1158959) | about 2 years ago | (#41509017)

I actually started out a physics major in college, and drifted over into English because Honors Calculus II with Theory kicked my hiney. (All my own fault: I spent my labs spinning equations around the axis and looking at the pretty pictures instead of learning the math behind it.) Not all English majors are automatically technologically deficient, especially ones who opted for a rigorous science and technology curriculum for their electives. I somehow finished with a minor in botany, which did nothing to help me find a job but everything to help me understand lab science and its specialized jargon.

talk to your PC (4, Insightful)

Simonetta (207550) | about 2 years ago | (#41508625)

Get a simple microphone like the blue-tooth-like headsets. Beg, borrow, or steal a speech-to-text program. (there's one buried in newer versions of MS Word) Train it. (for the S2T program in Word, you read the first few chapters of 'The Wizard of Oz' from the display on the PC screen).
    Now open a text file for your speech to go into and the software (or whatever) that you are trying to document. Describe what is displayed on the screen. Pretend that there is a beautiful woman next to you who is totally fascinated in the smallest most exact details of your program, and is totally in love with the sound of your voice describing it to her. If this is too much of a stretch then put a picture of your favorite gorgeous actress next to your PC, stare into her eyes, and describe your program to her.
      When you have a long and detailed text file describing your software project, close it and attach it to your source. Do this even if it means putting the whole thing in one long comment block and pasting it to the end of your Main file.
    Ignore all sentence structure, punctuation, and grammar mistakes in the file. You'll go crazy trying to repair them and most of the people who be needing this documentation will be so happy to have *anything* that they will overlook all the sentence structure, punctuation, and grammar mistakes in the file.
    If you don't speak English well enough to make the speech-to-text comprehend your words then either get a native English speaker to do all the steps above or use a Speech-to-text program that works with your native language. (if there are no speech-to-text programs that works with your native language, quit your present job and form a company is that based solely on making and selling such a program. Make it open-source free and have some NGO or your local Ministry of Culture pick up the cost). The people who are going to be reading the documentation in order to understand your program will either use a PC-based language translation program on your text file or hire someone at minimum wage to read your file and to translate it into more-or-less English.

    Read everything written above and Just-eF'ing-Do-It. Don't tell anyone that you did it. Just slip your rambling text 'documentation' file into the final shipping product disk or Zip file and let it be your little secret.
    Believe me, everyone who buys or uses your software will be glad that you did this. If you get fired, then become a consultant and teach other companys how to do exactly the steps described above and make twice as much money that you were before at the dingbat cement-head company that fired you.
    Just do it. Remember, every major advance in computer science made in the past 30 years was at one time called 'the stupidest fucking thing that I've ever heard' by Bill Gates. Speaking documentation to your PC seems stupid, but it gets the docs created when nothing else seems to work quite as well.

Re:talk to your PC (2)

pnot (96038) | about 2 years ago | (#41508843)

That's a really interesting approach. Are there any examples of it in the wild? I'd be keen to see what one of these narratives looks like.

Re:talk to your PC (1)

blade8086 (183911) | about 2 years ago | (#41508979)

no really.. just write the docs as you go. it doesn't take that long. if it does, learn to type faster, or use your editor more effectively, or stop being so lazy, because those are the real problems.

Three reasons (4, Insightful)

griego (1108909) | about 2 years ago | (#41508635)

I can think of three reasons why nobody WTFM:

1. It's hard. Would you want to write a manual for Excel or 3ds Max? I wouldn't. Where to begin and how to organize it?
2. It's time consuming. Software is bigger than ever, at least on the desktop.
3. It's not sexy.

Different skill set (4, Insightful)

Celarent Darii (1561999) | about 2 years ago | (#41508685)

It is very rare for a good programmer to be also a good writer. Heck in any job it is rare to find someone with two good skill sets. Even with the two skill sets you often only have time to do something well. I would have to say though when then planets align and the good programmer is also a good writer, usually some sort of standard results from it, and lots of progress is made in the field. Also, some projects don't really warrant the time to make extensive documentation. I wrote tons of LISP code that never had much of documentation because it didn't really need it and simply got the job done. I'm sure many projects never get past the stage of documentation on a need to know basis.

Re:Different skill set (1)

Misagon (1135) | about 2 years ago | (#41508889)

A programmer does not have to be a good writer, but a good programmer is a person who has good organizational skills, someone who can write lists of topics and subtopics that the documentation should include.
A good programmer is also good at reading and spotting errors in code .. and in documentation.

Therefore, a programmer could very well cooperate with a professional writer, where the writer does not have to be a good programmer:
The programmer could start writing a terse, stilted documentation. The writer could turn that into something that is more readable.
Last, the programmer could work with the writer to correct any errors or misunderstandings in the work. The result would be better documentation than if either did it on his/her own.

Bullshit (Re:Different skill set) (0)

Anonymous Coward | about 2 years ago | (#41508905)

Not to go all Zed Shaw on you or anything but that is grade-A, freshly squeezed bullshit.

Coding is explaining to the computer what you want done in very exacting detail. "Programmers" who can't write an explanation of what their code does can't possibly be writing very good code either.

The programmer knows what the user needs to do (s/he'd damn well better), the programmer knows what the code s/he wrote does, the documentation follows from there. Sure, it may not be Shakespeare, but it will be well organized and tell the reader what they need to know.

Re:Different skill set (1)

Alain Williams (2972) | about 2 years ago | (#41508937)

It is very rare for a good programmer to be also a good writer.

Maybe - but if the programmer does not write any description of what he has done, then someone who is a good writer has no chance at all. So: when you write the code, write (in English/...) what it is trying to achieve, why it is doing it and how it fits in with other code/programs.

Even better: write the documentation first and then the code. There are times that I have done that, realised by trying to explain what it has to do that my spec was not quite right, fixed the spec and documentation - the code produced later was better at doing what it was supposed to as a result. Code is easier to fix at the specification stage than when it has been written.

Literate Programming - Write both as one source (2)

WillAdams (45638) | about 2 years ago | (#41508689)

Knuth's source for TeX and METAFONT does this (he created the technique to enable him to write the system).

I've found (re)writing a program as a literate program results in a much cleaner representation of the code and algorithms and a clearer, more understandable manual.

DEK has since written an entire book on the concept (_Literate Programming_ a CLSI series book) a decade ago, but one seldom sees source so provided.

There are some really cool example programs which're quite interesting (and educational) to read, for example:

Will Crowther's game Adventure - available here: http://sunburn.stanford.edu/~knuth/programs/advent [stanford.edu] .w.gz (with an offer of a $2.56 reward check if one can find a bug), or as a document to just read here: http://www.literateprogramming.com/adventure.pdf [literateprogramming.com]

Or a CWEB version of the RPN calculator for K&R's C Book: http://www.literateprogramming.com/krcwsamp.pdf [literateprogramming.com]

People don't read em! (1)

p51d007 (656414) | about 2 years ago | (#41508701)

Heck, I can't even get techs to read the service manuals sometimes, how are you going to get end users to read them? All of our equipment use to have a place on the back, that held the manuals. I use to say I could slit the plastic wrapper that came on the manuals & drivers, slip a 10 dollar bill into the book, come back a year later & would have a better than 70% chance of finding the 10 dollar bill exactly where I left it! Now, our manuals come on PDF included with the drivers disk, plus a small "basic" book, and they still don't read them, even though with a PDF it is searchable.

Where's the money? (4, Informative)

tommituura (1346233) | about 2 years ago | (#41508737)

A cynical answer is that even if the language or framework author/project head was a technical writer worth his or her salt, it makes more sense to write a book and sell it. Because asking money for the language (compiler/interpreter+libraries) itself is not going to fly in the flooded market of programming languages unless it is really really good and only very few of them are actually that good. Maybe not even then, because the price tag of non-zero value is poison for easy availability which is a must if you want someone to look into your project or language on his or her free time. With frameworks you might get more leeway but not much, especially not if you count on having a hobbyist/hacker community to flourish. Of course, getting someone like O'Reilly to greenlight your book about your own virtually-unknown language or framework might prove to be tad difficult too... Of course, if you're someone like Apple or Facebook or Microsoft or Google who offer a platform with sizable userbase with monetization prospects, this isn't really a problem.

And then there is the fact as noted in submission that writing a good manual takes a different skill set than designing and implementing a good programming language. If you don't have it, someone else has to take up that work if it's going to be of any use. And for that to happen, the language or project has to exist in some kind of usable, stable state long enough for those "outsiders" to actually study and learn how this thing actually works.

Which brings me to the last point. The really good books about a given programming language or framework give also "learned in real world use" insights about the pitfalls, deficiencies and suggested "usecases to avoid and the usecases to strive for" of the language which might only be discovered afterwards. This also might or might not be easier for someone who is not intimately knowledgeable with the inner workings of the language or framework by the virtue of being the one who created it. You kind of become blind for the real merits and sore spots in your own work, so to speak.

And fwiw, I actually have no problem with the idea of paying for a book to help me learn a language / framework I want to know how to use. I have even done that! I do, sometimes, lament the fact that online documentation is lacking because looking up things is usually easier on those than on dead tree (or PDF files simulating dead tree).

I do share some of the sentiments of TFA though. Most infuriating is when there's a "quick and easy tutorial"... which also doesn't cover very much beyond the simplest of use cases and then theres a very terse api reference. And virtually nothing in between. At that point I usually ask myself "do I really have to / want to (+ have time to) learn this thing, and is there a good book on it?"

Re:Where's the money? (1)

TheGoodNamesWereGone (1844118) | about 2 years ago | (#41508767)

It's a catch-22... If you want people to understand your language then you'd better have a good, comprehensive (and preferably in book form) manual, but you won't make any money off that book and language until it becomes popular.

You want me to write manuals? Pay me. (2)

Tanuki64 (989726) | about 2 years ago | (#41508743)

I am a freelancer, I am doing what the customer pays me for. I also write open source software in my free time. You don't like it? I don't care. I don't do it for you. I write it for me. I don't need a manual for my own code. So why do I publish my code at all? Why not? Maybe it is useful for someone. I just don't feel any obligation to make it useful for anyone but me.

Re:You want me to write manuals? Pay me. (4, Insightful)

techno-vampire (666512) | about 2 years ago | (#41509007)

I just don't feel any obligation to make it useful for anyone but me.

I'm sorry to say it, but if that's the way you feel, there's very little chance that anybody will ever get any use out of your code. Most people are only interested in using programs, not in fighting their way through the code trying to learn how to use it and for many people, if it doesn't come with instructions on how to get it working, it's not worth installing. At one time, that was mostly a Windows attitude, but there are more and more Linux users today who expect at least a little documentation, and as time goes on, their numbers are only going to grow.

No WTFM (0)

Anonymous Coward | about 2 years ago | (#41508751)

People only need manuals if the thing is hard to use.
If you have only one button that says "DO!" then nobody needs a manual.

Are you patient enough to teach another person? (3, Interesting)

MarkvW (1037596) | about 2 years ago | (#41508771)

I'd love to work on a manual for something I'm really interested in, like Blender, but I doubt that any developer would have the patience to teach me what he knows--all the while trusting that I am going to complete what I set out to do.

It's a problem.

Re:Are you patient enough to teach another person? (0)

Anonymous Coward | about 2 years ago | (#41508969)

I do write small manuals for myself, for the software I occasionally use. Whenever I encounter a problem with some software, I search it on google and some solution is found for it most of the time. When I find it, I don't simply use the solution and forget about it. I also write it down in a text file along with other problems I have encountered with the same software so far. This way, I get a compact tips-and-tricks/howto document which isn't a manual, but is very useful. I have some pretty old documentation I made this way which still apply to current releases. If there was a way to share these documents with other guys who do the same thing and a way to merge the documents, I think the resulting thing could come very close to a manual.

Adopt the Microsoft Press Model (1)

Pop69 (700500) | about 2 years ago | (#41508773)

3 page getting started guide, sell a 3 x £50 books instead of inculding a manual

Even if there is a FM ... (1)

whoever57 (658626) | about 2 years ago | (#41508785)

I have come across many software projects where TFM is either a set of examples, none of which match what I am trying to do and lack sufficient explanation of the examples for them to be usefully extrapolated to other use cases, or a description of the syntax of the input files with no examples of how to use it (so the semantics of the input files are not explained).

Both examples and explanation are needed.

Re:Even if there is a FM ... (1)

MobileTatsu-NJG (946591) | about 2 years ago | (#41508847)

I work with some very powerful software that has a fairly good manual, but some of the examples are written like this:

$x = exampleFunc(1, 2); // result = 1;

$x = exampleFunc(2, 3); // result = 1 ;

Thanks guys, that really cleared it up.

Nobody has addressed the examples (1)

Areyoukiddingme (1289470) | about 2 years ago | (#41508789)

And I'm not going to address the examples either. At least, not exactly. I use Google's Protocol Buffers in a project, and figured out how to use it from Google's documentation. Except I still haven't figure out how to use the ZeroCopy classes. The documentation is that bad. It's horrific. It exists, and tells you the first dozen things you need to know. Then it STOPS. And doesn't tell you anything else. I swear Google puts it up as a test. If you can figure out how to use it from their docs, you get a prize.

(Though that theory turned out to be wrong. Google recruiter did call me, but her group declined to interview me further. No prize for me.)

Re:Nobody has addressed the examples (1)

sandytaru (1158959) | about 2 years ago | (#41509061)

We ordered a $2,000 Linux based backup server, which came with exactly 11 pages of setup documentation, most of which is screenshots. It included such gems as, "Now set up the network" and had a screenshot of the link to the networking page. Then it went on to the next section. While most of the fields on that page were self explanatory, there was no mention of the fact that only one NIC was supposed to be set up; the second is set up only if/when you need to run a virtual server as the backup, and not on that networking page, but on the page where you set up the server! Two hours of a tech support call later, someone finally figured out that was the issue.

Docs are for the trashbin of history (1)

michaelmalak (91262) | about 2 years ago | (#41508821)

The forces that brought about written documentation were:

1. Computer RAM too small to hold a document, lack of multitasking (in DOS days), and lack of screen resolution/real estate (even pre-dual monitor days, which was only 2-5 years ago).

2. Release cycle of software was annual or longer, rather than automaticaly patched daily from the Internet.

None of those is true any longer. Software should be self-explanitory. And if it's not, there is now an alternative:

YouTube

It's fairly simple to run a screen capture on your laptop with its built-in microphone. It shows the typical run-through, or use case to use the technical term, which is enormously helpful for first-time users. If you can't handle that, then you'd better hope you gain a fan who spontaneously does it for you.

You want a serious answer? (1)

DaveV1.0 (203135) | about 2 years ago | (#41508829)

The creators don't actually give a fuck about documentation. They don't need it and if you need it, that is your problem, not theirs. Can't figure it out? New adopter? Tough shit, ask the "community" so you can be told "RTFM, n00b!". Then, you can try Google where you will find 5 pages of people asking the same question and getting either the same or no answer.

Back to reality (0)

Anonymous Coward | about 2 years ago | (#41508845)

Writing a manual is somewhat tedious but still the easy part. Writing a manual that conveys information is a completely different beast and out of reach for 99% of programmers.

And even after you have managed to put together a good manual that conveys the information nicely, you will find that (1) few people will read it, (2) of those who do, few understand it and (3) the manual will not be kept up to date.

So what happens is that there's a token manual that contains random information in a useless form and nobody bothers to read. The customers of the system will improvise and when it fails, they will send their setup to you for troubleshooting, debugging and reimplementing.

It starts with a website (4, Insightful)

Gadget_Guy (627405) | about 2 years ago | (#41508883)

The problem isn't just with manuals. It starts with a website. As a programmer, you might rely on other people to write your documentation but those people will never even learn your product without knowing what the hell it does.

I have lost track of the number of times that I have stumbled upon a project's website only to be confronted with a changelog rather than a description of the product. There have been some (mostly open source) programs where I have eventually left the site without ever finding out what the software was actually for.

Every webpage should have a short statement of what the project is designed to do, along with what OS it runs on. You don't have to be a great tech writer to do it, just imagine what a complete newbie would want to see the first time they happen across your site.

Don't assume that your audience are also programmers and you might just get people interested who can actually write your documentation for you.

It's hard! (1)

emblemparade (774653) | about 2 years ago | (#41508921)

I've initiated and maintain several large free software projects, and I agree wholeheartedly with the basic premise here: I think that software without documentation is close to useless, and I put huge amounts of effort into it.

But, let's be realistic here: it's a LOT of work. I can easily spend more time maintaining the documentation than the code. I consider it time well spent, but realize (as others have pointed out here) that it's a different kind of skill-set, which programmers don't always have.

The bottom line is that I would rather people release software than not release it a all. (close to useless != useless). Still, I wish more projects would take this issue more seriously.

the 20something Entitlement Culture strikes again (0)

Anonymous Coward | about 2 years ago | (#41508923)

*orders latte at Starbucks while checking messages on android*

*fires up ipad*

"Boy, a lot of this free stuff created and posted by people in their spare time kind of sucks! Maybe it's useful, but I can't figure out how to use it right away.

If they expect me to stick around, they need to do a whole lot better. Either do the kind of work that they aren't skilled at doing, or hire someone who's good at it! And I shouldn't have to pay O'Reilly or Manning for the manual that's supposed to come with the software.

My time is worth money, you know!"

*sips drink, surfs /., updates Facebook page*

*posts article on blog*

"That's my advice... maybe they'll thank me for it."

UTSL (0)

Anonymous Coward | about 2 years ago | (#41508949)

Use the source Luke

Great examples: Ruby and Qt (separately) (0)

Anonymous Coward | about 2 years ago | (#41509039)

Two great examples of documentation so good I learned how to use the tech: Ruby and Qt. Both had complete web tutorials/examples and excellent help web pages. I don't know if I would have bothered to learn either had their documentation not been so good.

"Get your documentation off my lawn!" (4, Insightful)

PolygamousRanchKid (1290638) | about 2 years ago | (#41509055)

We used to put older programmers out to pasture writing documentation. Despite their cranky "Get off my lawn!" disposition, they were very good at it, like grandfathers telling a story:

"Children, let me tell you a story from a long time ago, in a far away place, about an associative array of function pointers . . . "

But now we lay off the older programmers.

And now we outsource the younger programmers, so they won't even get to be older programmers.

So there's your documentation for you, right there.

Docs are first thing I look at. (2)

Zadaz (950521) | about 2 years ago | (#41509075)

When I need to evaluate some new tech, be it an API, language, tool, or just about anything else, the first thing I look at is the documentation, after that I look at the community support. Because I know I'm going to get stuck at some point and I need to know that there will be a way out. Even if another tool will technically be a better fit for what I'm trying to do, I'll still give it a pass in favor of a tool that I know what it can and can't do.

Not that good docs are easy, they're not. They take lots of time, even for bad ones, but if you want to see adoption you need docs that include usage examples. This is primarily why Open Hardware companies have been growing like crazy while Radio Shack stagnates. They don't just sell a 555 timer, they provide dozens of free tutorials showing all the cool shit you can make with it.

Information Mapping (3, Insightful)

SplashMyBandit (1543257) | about 2 years ago | (#41509161)

Most developers hate writing technical documentation, and when they do they organize it poorly. I was trained in the "Information Mapping" school of tech writing that is based on the psychological aspects of learning and human working memory. The Information Mapping style has numerous benefits:

  • * the information you want to convey can be broken into seven types
  • * information 'chunked' into parts that are easy for the reader to digest
  • * documentation is designed that you can skip to the part you need without having read much of the rest of the documentation
  • * it is easy for the writer as they simply follow the information mapping process, you don't have to think too hard to start writing, unlike when you try to write without any structure, and
  • * the documentation that is produced has little prose, so is quick to relatively produce.

Once you have the basics of Information Mapping then as you grow you get better at quickly structuring everything as well as writing examples and unambiguous sentences that can help your learners to avoid many pitfalls.

So, I believe the premise of this thread is correct, many manuals either don't exist or are poor from a learning perspective. The most surprising thing I found when I learned Information Mapping (only takes a day to go through, since it is far easier than learning a programming language, and from then on it is just putting it in to practice) was how easy and effective it is. nb: I don't get kickbacks or anything from Info Mapping, it just happens to be the best and most time-efficient tech writing technique I've seen, so I hope me mentioning it helps someone else who wants to learn to be a great developer (which involves being a great communicator too).

ps: info mapping is about structure and content selection, unfortunately it doesn't help with my typing or (lazy) proof-reading :)

How to get TFM Written (1)

Tsu Dho Nimh (663417) | about 2 years ago | (#41509163)

Almost every university has a technical writing department. Those students often need real-world projects for their classes.

Call the professors and ask them if they would like some real-world software for their students to document.

Load More Comments
Slashdot Login

Need an Account?

Forgot your password?