Comments on: Documentation: the missing tyre

By: Perspx : Updates: the software after-party

Perspx : Updates: the software after-party — Tue, 05 Jan 2010 17:32:18 +0000

[...] Documentation: the missing tyre Naming is hard [...]

By: perspx

perspx — Sat, 26 Sep 2009 21:40:39 +0000

Yes I agree – I see loads of people who don’t look at documentation for things at all because they know they won’t find anything useful, which I guess is fine for certain products because you can – in a lot of cases – stumble around and find what you want anyway.

However I was talking more specifically about technical documentation which you DO need to read in order to know how to use some API or framework (you can’t exactly stumble around a framework and expect your application to be robust) – yet a lot of it is poorly documented which makes the whole process a hell of a lot more painful.

By: rx512

rx512 — Sat, 26 Sep 2009 21:35:21 +0000

Funny thought, even if your documentation is amazing, since 99% of docs out there well.. isn’t, people aren’t likely to look at it.

Take my mum.
She wasn’t sure how to superscript in OpenOffice when she was typing something up on my OpenSUSE laptop a few hours ago.
She just left it as is, and when I asked her why she didn’t look at the docs, she said that she knew she wouldn’t find anything useful in there xD
And she’s like, technologically illiterate.

By: perspx

perspx — Fri, 25 Sep 2009 15:51:51 +0000

Ah, great cartoon!

And yes, I don’t think in most cases it’s intentional, but developers forget that other developers don’t know how their code works, especially so if it’s something that they have been working on for a while and know inside out.

By: Diago

Diago — Fri, 25 Sep 2009 12:50:37 +0000

Well said. I have that exact image up in my cubicle at work, along with the image of how Apple and Google design software. I am in charge of training a group of about 40+ hardcore developers in .Net, and I find examples of the above every day at some point. It’s amazing that we have 200+ Delphi applications running our business because of this.

Thankfully being rewritten now, with that image reminding me everyday of what NOT to do.

By: perspx

perspx — Thu, 24 Sep 2009 05:56:54 +0000

> People should look at jQuery’s documentation for great examples of examples

Yes the jQuery documentation is great because there are so many pieces of example code, and there is also an overview section to each API function which explains a bit about the function as well.

By: Ólafur Waage

Ólafur Waage — Thu, 24 Sep 2009 00:11:00 +0000

The second point gets me the most. I have the documentation of some item, it says that I can use it in some way but it doesn’t show how.

So examples or a place for examples is an awesome addition to any documentation. People should look at jQuery’s documentation for great examples of examples