Comments on Abakas: No, We Shouldn't Document That

Hi Catherine, Good post. I wrote one myself bas...

2010-06-15T14:13:06.165-04:00

Hi Catherine,

Good post. I wrote one myself based on yours here http://www.testalways.com/?p=72.
The "Release Notes" also are a too easy get-away and will not make customer very happy. But in principle I think companies usually care about usability and try to improve. But also heap of documentation is building up in parallel :)

Sebi

I don't think anyone is saying that all docume...

2010-06-15T02:09:56.531-04:00

I don't think anyone is saying that all documentation is evil -- it's just a "smell" and hence and opportunity of seeing if we can make it clearer/more obvious and hence simplify the documentation.

I think this depends on whether you are targeting ...

2010-06-14T20:47:39.114-04:00

I think this depends on whether you are targeting expert users or not. We typically end up with a substantial bit of user documentation in our work, but our users tend to be in the application eight hours per day. Sometimes things are harder to learn, but increase the system throughput, so they make sense to keep, like the keyboard shortcuts in GMail or Excel.

Configuration options for changing the number of request threads your web browser opens need to be documented, how to go a back a page shouldn't need to be. User documentation isn't all evil, right?

I would say that any perceived need for documentat...

2010-06-14T18:38:47.057-04:00

I would say that any perceived need for documentation is a good point to think about how to simplify that documentation (possibly to nothing). As you said, if you make things work nicer/better/more obviously (or just work), you might have to write and maintain less documentation.

If it's hard to describe how it works, perhaps it shouldn't work that way!

Sakamoto - sure. We usually call those "Relea...

2010-06-14T17:26:03.905-04:00

Sakamoto - sure. We usually call those "Release Notes" and specifically the known issues section. Bugs get documented in various ways; it's just important that the documentation not be a replacement for the bug.

I also agree with 'Every "we should docum...

2010-06-14T17:07:37.269-04:00

I also agree with 'Every "we should document that" is a bug until proven otherwise' but to a point. There are cases where if the customer submits a defect onto your product, your company has to pay for that defect, unless that has already been documented prior to release. Would documenting everything you see help prevent these costs? Or would it make matters worse by scaring customers away?

Joe, you're right. Just because it's a bug...

2010-06-14T09:58:48.114-04:00

Joe, you're right. Just because it's a bug doesn't mean it'll get fixed for this release, for the next release, or ever. Treating it as a bug allows you to make that decision explicitly, though, rather than sweeping it under the rug with a casual "it's documented!"

I agree with 'Every "we should document t...

2010-06-14T09:41:50.386-04:00

I agree with 'Every "we should document that" is a bug until proven otherwise'.

But sometimes the business needs, priority, available resources, where you are in the release cycle, etc requires that a "we should document that" bug be fixed via documentation, rather than a code fix.