The Old New Thing

"Imagine if you told everybody that the product was late because we pulled the development team off of fixing bugs and told them to write documentation."

Ahh, this assumes that lack of documentation is not a bug/flaw.  It is all about what you view as the "product".  I would venture to say that a far superior approach is to elevate documentation to the position of a first-class feature of the "product", much in the same fashion that the SDL has supposedly done with software security.

Thus, the missing documentation is an incomplete feature or it is a bug, and can be treated as such.

Of course I have completely glossed over the fact that your post was about the Imaginary Month-Long Documentation Drive (or as I will affectionately name it... the IMLDD).  Nothing to see here... please move along.

That would make more sense if everyone were good at writing documentation.  You shouldn't take me off the product I'm working on to create images for buttons.  It's not in my skillset.  You shouldn't pull everyone off to work on technical documentation.

I think this boils down to just because you can do X doesn't mean that X will actually solve the problem.

Well, a good point perhaps, but the problem with documentation is scope creep: what do you tell, and who's your audience? Do you tell _everything_ to _every possible audience_? It simply can't be done.

Define what you mean by documentation first, then we can decide if a month is sufficient.

No amount of documentation is the right amount until the scope and audience are decided - it will always be too much and too little, too elementary and too hard, and almost always at the same time.

"What's more, technical people tend to write documentation for other technical people, on the assumption that the reader is already familiar with the material."

For the documentation that developers refer to every day, this is a Good Thing; if you're wondering what the order of arguments to CreateProcess is, you don't want to have to wade through five pages of explanation of the underlying principles to find it.

The problem comes when that's the *only* documentation you have, since it's hard to get anything other than "What does that argument mean again?  And how do I deallocate resources this allocates?" out of it.

I don't think a month would be require for a review; I think the reviews for most new technologies could be complete in a day. I agree that the developers shouldn't be asked to write the docs, but reviewing the public docs should be a requirement before RTM.

The Windows developer doc teams used to have a "Long Last Look" before major releases where doc team members would look through as much of someone else's project(s) as possible (the goal being to put eyes to every page). With current staffing levels this doesn't happen regularly any more.

Textbite: Good documentation leaves no doubt.

It may not be reachable, but that's what you should aim for.

One major pitfall, as already mentioned, are the peer to peer assumptions--acceptable in peer to peer communication, but time consuming for everyone else.

I have thought about this a lot when documenting file formats, in which there are many assumptions at work today that may be require time in the future; like what kind of signed integer encoding is assumed (one's complement, two's complement), endianess, whether a byte is eight binary digits or nine in a given context, what a 'word' is, etc.

There's still something skilled technical writers miss often, and that's understanding a present context (like "now I *have* to do *this*, how should I do *this*", where a section is made for that *this*).

In API documentation, however, you already have a structure, but may miss how to logically group the things it represents, such as the protocol for using the API, separated from the concept it represents.  Being clear on the limitations from the start, such as ranges; common pitfalls that the developers have experienced, and are aware of may be vague--anything to save time--time that the IT industry killed enough of during one today as is.

The most important is the fundament--the philosophy--why it was done this way instead of that way, what the designer was thinking. Writers will skip the philosophy part, because they'll avoid attacks on their exposed decisions, once put into words. The reason they should write the why is because it helps the learning process, and the broader understanding, which will make it easier to fit the information in your head.

People who criticize Microsoft generally assume either that Microsoft is a mom-and-pop software developer with 4 employees, or that Microsoft has never heard of "specialization" and all their employees are equally good at everything.

Just ignore criticisms like that, they're obviously from people who have no clue about software development, or how to make large projects work.

"Imagine if you told everybody that the product was late because we pulled the development team off of fixing bugs and told them to write documentation."

- I think common management practice is to tell people "This is the month where everyone focuses on documentation/security/whatever, but do this without delaying any of your other work."

If you let devs write documentation, then you can expect "documentation" like this:

DWORD SnapWindow(HWND hwnd): Snaps a window

No s***, Sherlock!

When I run into documentation like this on MSDN, it's usually on some ancient COM interface. I've seen it in a few open-source Java packages as well.

"Well, part of it is that most people suck at technical writing. The technical part, maybe, but the writing almost definitely not. Writing is hard (as I've learned firsthand), and technical writing is a special genre of writing that requires a comparatively rare skill set, combining technical background with strong writing skills."

Sounds like a totally lame excuse to me. In the first post you linked to you said, the doc team relies on the devs for info and that the devs dont write it themselves. You have two sets of people one good at writing, one good at the technical stuff. So whats the problem here?

Also does anyone else get the feel that Raymonds writing has a tinge of the "victim-complex"? I've been reading this for a while but Its one of those things that you don't notice because it happens gradually over time. Maybe I'm wrong.

@I'm Old

"Also does anyone else get the feel that Raymonds writing has a tinge of the "victim-complex"? I've been reading this for a while but Its one of those things that you don't notice because it happens gradually over time. Maybe I'm wrong."

Not for nothing but what does it matter what "tinge" he may have? Does it somehow make you feel good to point that out? Maybe we could all sit around and poke fun at Raymond? Kick sand in the guys face?

I have to admit the personal attacks on Raymond really wear thin over time. I mean seriously does it make you feel good to "stick it to the man" or something? +1 against evil M$

Lame excuse? Boy I would sure love to audit your code someday. I am sure you've never made any poor decisions ever, regardless of intention. I am sure you never had to drop a feature to meet a deadline. Never had to skimp on documentation, if you even write it at all.

He's pointing out difficulties we all have when tasked with writing documentation. Point blank, it's hard, and you're not going to be able to please everyone all the time.

Microsoft, like any company, like your company if you even write code in a collaborative environment will have various strengths and weaknesses that ebb and flow over time.

I for one am happy to read every so often that we're not the only ones who have tough decisions to make, and occassionally making a wrong one comes with the territory.

Raymond, please continue to write in whatever tone you feel like. Your interaction is appreciated and not taken for granted.

Sorry for the rant.

Godzila

"Not for nothing but what does it matter what "tinge" he may have? Does it somehow make you feel good to point that out? Maybe we could all sit around and poke fun at Raymond? Kick sand in the guys face?

I have to admit the personal attacks on Raymond really wear thin over time. I mean seriously does it make you feel good to "stick it to the man" or something? +1 against evil M$"

Yeah, it makes me feel good. Shows how cool I am. I get instant geek cred. Right? Yawn.

"Lame excuse? Boy I would sure love to audit your code someday. I am sure you've never made any poor decisions ever, regardless of intention. I am sure you never had to drop a feature to meet a deadline. Never had to skimp on documentation, if you even write it at all."

I don't need to display my credentials to you or anyone else to make a point. Sort of like, I don't have to be good at baseball to make an observation on a players or teams performance. It might carry more weight if I was a player, but doesn't invalidate the point on that basis.

"He's pointing out difficulties we all have

when tasked with writing documentation. Point blank, it's hard, and you're not going to be able to please everyone all the time."

I guess you decided to skip logic (or reading what I wrote) here. Go and re-read. The perceived "difficulty" is a circular chain of logic.

1. Devs dont write code, doc team does.

2. Doc team gets their information from devs.

(so raymond cant force them to improve docs)

3. So why doesnt MS ration out time for improving docs?

4. Because writing technical docs is hard ! Also developers are not good at writing !

5. Um.. <wtf>

Also, this isn't a mom and pop shop we're talking about. This is a huge giant corporate, the most successful software company. Hell yeah, I expect them to hire a few people and get the docs straight.

A word of advice - fanboy rantings get old.. real quick. Next time try and come up with something that doesnt look like a 2 yr old wrote it.

It's all about the priority. The doc should be a joint effort between the Marketing and Product Development. If the Marketing does not care about the product description, what the hell nobody cares about the doc. For the MS product, it's the monoply, you can not live without it so no use to spend too much the time with doc period.

@I'm Old:

Raymond's post isn't about whether documentation should be written.

It's not about whether someone should be dedicated to the task of writing documentation.

It's about whether DEVS should be dedicated to the task of writing documentation. Get it?

@I'm Old... Did you read what Chen wrote? He wasn't saying Microsoft shouldn't fix the documentation. He was saying it was pointless to take people who don't have a particular skillset and make them perform that skill.

If something is broken, the way to fix it isn't to get people who don't know how to fix it to fix it.

It isn't so much that writing documentation is hard. The problem is that, generally, programmers don't write good documentation. The current perception is the documentation isn't good, so the solution is to make people who aren't good at writing documentation, write the documentation. How does this solve the problem?

Even if the programmer is good at writing, Raymond pointed out another issue, in that it isn't always obvious. The programmer, who knows the code backwards and forwards, may not realize that the documentation doesn't really say what he thinks it says.

"It's not about whether someone should be dedicated to the task of writing documentation."

It's about whether DEVS should be dedicated to the task of writing documentation. Get it?"

That would make sense if the very first link didnt cite his own words saying doc team NEEDS devs to write technical docs.

Let me place it here for your benefit.

"The documentation group relies on the development teams to provide the technical information in the first place; it's not like they can just write the docs without any help. And I suspect they have higher priorities than touching up ancient Win32 documentation."

-

Actually I don't expect bitching about it here to change anything. Only hope is someone from the bloated middle management sees this and agrees with it. I mean they cant _all_ be delivering crappy products and at the same time leeching on Windows/Office revenue stream, right :P (OK that was not necessary, and can be removed if moderator-snarky-filter is set too low)

Good post, Raymond. Although it seems 'obvious' to me that not everyone is good at writing technical documentation and it would be a bad idea to force them to do it, apparently it isn't obvious to everyone.

@I'm old: Someone not being good at something is a "lame excuse" for not paying them to spend all of their time doing it? Really?

People, ignore the troll.  Ignore the troll.  Don't feed the troll.  As soon as someone starts replying line-by-line, or calling other people a "2 yr old", it's time to move on.

Documentation is hard to write. Agreed. I programmed in many different environments and must say that the most of Win32 is exceptionally well documented. Most of .NET is well documented. There may be areas where MSDN does not shed enough light but the problem I encounter most often is developer not _reading_ the MSDN documentation before implementing their code. When I debug some broken areas heavily interfacing with Microsoft, more often than not reading the MSDN documentation is sufficient to clear up the bugs.

I have to admit that DDK/SDK documentation is getting better. And thanks to the feedback links in it, it's quite easy to submit a doc bug. That said, the docviewer got worse. Search in it is even slower than search on internet. BUT, it's still not as bad as vista/Win2008 help. Boy, this thing is UNUSABLE. While in XP help you could find pretty much what you wanted, in Win2008/Vista you get a whole bunch of arbitrary crap. Search, for example, for cmd. Looks like full text search is not a good solution. (Vista bash redux!)

Dijkstra told a story about the tendency of programmers make up names for concepts as they design a system:

http://www.cs.utexas.edu/users/EWD/transcriptions/EWD06xx/EWD648.html

(starting at "When the design is complete")

I think it illustrates the problems the developers of a system can have when writing documentation for it By the time a system is finished, the terminology used within the code can be a complete lie, based on assumptions the developers made 6 months ago that turned out to be wrong.

By that time the devs are spoiled for writing documentation, because they have accepted the inaccurate terminology as a fact of the system. You want to bring in an outsider who can document the system in terms the rest of the world understands.

I spoke at a "Career Day" at my daughter's school (ages ~11 to 14) last November.  When asked what classes would be important for a career in technology, I pointed out the obvious, like typing and computer classes, but I put a HUGE emphasis on learning how to communicate effectively, particularly in writing.  That's not just for technical writers or salespeople, but also for the work-in-the-dungeon-by-candlelight uber-nerd developer types (like me).

Most developers think that they are good documenters, when they bother to document. This is similar to how most poker players think that they are good poker players, when they bother to try to play well.

The reality is that comments such as..

i++; /*increment i*/

..are more common than seems reasonable, and this is because people have been taught that they SHOULD document, but not WHAT THEY SHOULD document.

Good documentation documents THE DATA and when important, THE REASON BEHIND IT.

This is because, for the most part, CODE should be self-documenting! The code itself should be a concise description of the algorithm used. Proper naming of variable and functions goes a very very long way WRT self-documenting code.

There was a time, not so long ago, that there was an attempt to also document the data by using clever variable decoration gimicks.. AKA hungarian notation. This failed to stick for many different reasons, but primarily it was because it didn't do a good job of it.

Its just noise because when I am looking at the code itself, i'm trying to discern the algorithm, not data specific details which shouldn't have issues when employing proper type safety.

I largely agree with Raymond, both from the fact that most coders can't communicate (relevant comments are sometimes few and far between) and that there's got to be a relevance limit somewhere. Some features are meant for 0.00001% of the users and someone has to draw the line where documenting is not going to pay off.

Unfortunately, when you're in that 0.00001% you really, really NEED the info because even <preferred search engine> can't help you. I'm currently delving into <database product> and trying to figure out why certain performance parameters are plummeting when nothing special is going on. I can't find help on the numbers and functions I'm using anywhere - I'm out fishing and have no idea what I'm catching. If there was some way I could identify myself to <vendor> and say "Hey, I'm beyond 3rd level support, give this question to someone who REALLY know's her/his stuff", I'd be more than happy to accept the state of the docs. I can't, I have to take it all the way up from 1st through 3rd through complaints and beyond before there's even a glimmer of hope of getting something I don't already know, and the customer will have converted to <other vendor> before I'm through.

So the whole docs/no docs question boils down to: how can we efficiently serve enough knowledge to enough of our customers to make money in the long run? Some can be served by docs, others need a developer site, forums, Raymond... And then there's the group in need of special care, for whom docs may not be the right medium. But how to filter the rest out with a "Read The Fine Manual" without pissing them off is quite beyond me. I'm a coder, not a manager... :-)

I think improving documentation would be fairly easy if MSDN would be more Wiki-style. So far, there are few user comments to the articles. I don't know why this is, but it would make an awful lot of sense to try to get developers to leave their comments and problems with the articles they are concerned with. So far, there are user forums, but they are quite apart from the main articles.

We've actually had a "week of documentation" at work.  A lot of work was done, but years after  the "last accessed" date showed hardly any documentation had ever been opened. Even new hires turned directly to the source code.

Documentation for the sake of documentation is fruitless.

I wonder if it's possible to use the data from the "Customer Experience Improvement Program" to see how documentation is used?

I think Doxygen is the worst thing that ever happened to API documentation.

Now many programmers think they have documented their APIs when all they've done is convert their header files into HTML.

(Or, if we're talking Java, convert their source into the equivalent of header files, then convert that into HTML.)

It's just annoying. You go looking for more information and just find the same thing you already had from the source in a slightly different format. Something that any decent IDE could produce for you on-the-fly as well.

MSDN Library isn't perfect but I think it is very good considering the amount of stuff it has to document. My biggest complaint with it is more a Visual Studio issue: Push F1 on a message or function name in a Win32 C++ project and you'll be taken to a page about MFC, .Net, Windows CE or just about anything other than the actual thing you wanted help on. This is despite the IDE clearly knowing it's looking at a Win32 C++ project. So frustrating. But not as frustrating as most Doxygen garbage.

@Leo Davidson: Agreed on MSDN.

@Leo Davidson: Agreed, on all three points (MSDN docs are generally good, Doxyggen docs are generally bad, F1 context is generally idiotic).

I don't think that developers should be *writing* docs, as a general rule (for exactly the reasons Raymond specified), but where public documentation is already part of the project (eg. for a library API) then the devs should at least periodically review the docs and make sure that they're up to date, or that they get marked to be fixed up.  Then the tech writer can get together with the appropriate dev to translate the dev-speak changes into proper documentation.

1) In general, Writing gets easier with practice. I hated English class in HS, but because I stuck with it and wanted to get good grades I tried my best to write well. I also realized it would translate into better grades in other classes like History, etc. The more you write, the better you will get. (Assuming that you actually have someone read your writing and give you feedback.)

2) Technical Writing requires that you first define your scope (or target audience) before you start writing. I generally assume that most people reading my technical writing have the most basic of programming/technical skills, but don't really understand anything outside of that. So perhaps at times, my writing seems a bit verbose or even simplistic, but it is only so that I can easily transfer my knowledge to others who need it without having to slog thru stuff that I did.

3) While writing about technical subjects, it is important to remember what it was like before obtaining said knowledge. This is tricky as once one becomes knowledgeable in a field, it's hard to remember what it was like to be ignorant.

4) Standard template/Structure. I find it helpful to have a standard structure to fill when I write documentation. It allows me to figure out the flow of what I'm writing and then outline when needs to be said. After this is done, it's frequently just a matter of filling in the details.

5) When all else fails, get an intern or a junior programmer to read through all your undocumented code and document it for you. Not only will you now have a second person who knows your code, but chances are he/she will have discovered some bugs in your code which you can stomp.  :)

The designer of a system is the worst possible person to write the documentation, even if they are great at technical writing.  The designer is too close to see the forest for the trees.  The ideal people to write documentation are new users, writing as as they go along learning the system.  

Wiki documentation makes that ideal situation not only possible, but common.  Antonio got it right;  MSDN should be a Wiki.  The "community area" at the bottom is a tiny step in the right direction, but it's not nearly enough.

The designer of a system is the worst possible person to write the documentation, even if they are great at technical writing.  The designer is too close to see the forest for the trees.  The ideal people to write documentation are new users, writing as as they go along learning the system.  

Wiki documentation makes that ideal situation not only possible, but common.  Antonio got it right;  MSDN should be a Wiki.  The "community area" at the bottom is a tiny step in the right direction, but it's not nearly enough.

[quote]The designer of a system is the worst possible person to write the documentation, even if they are great at technical writing.  The designer is too close to see the forest for the trees.[/quote]

That's a bad excuse for avoiding "unpleasant" work, however, some developers seem to like it.

I think it is a good idea to have developers write documentation, but it should be broken into a few cycles where developers spend a day or two providing input to the doc-writers, who punch it up and feed it back to the developers, who are then able to see how their input was transformed, what information they were assuming was known, and can perhaps improve their input for the next cycle.  

Those developers who turn out to be not-bad at documentation probably would be good candidates for other positions that require interfacing with external groups, so this exercise can help management match people to positions, as well as give people an opportunity to shine outside of their currently-defined roles.

Just some idea...

I think it's best to have the doc writers write the documentation, then assign some summer interns to review it and see if they need more clarification, and add remarks and/or links where applicable.

Afterall, most "new developers" are CS students, and "new developers" are supposed to be the major audience for these documentations.

======

Actually, for those who don't satisfy with MSDN documentation quality, why don't you just leave your feeback in that pages' suggestion box? In certain sense, it works just like a moderated version of wiki.

Well, I was just wondering... (I could be wrong), but I think most developers avoided writing documentation for other reasons too. Writing skills are part of the factor but I think the most significant factor is job security.

It's a bit shallow, but I fear a valid human concern. I think most developers feel threatened if someone can just take away what they have worked so hard to achieve. By creating a dependence, it ensures that you have a value in the company. It is not a good mentality but people does do it. That is why there is such a thing called obfuscation of code. They will tell you things, but not everything you need to know.

just my two cents. :)

PingBack from http://nobugleftbehind.com/software-quality-digest-2009-02-04/