What’s up, Doc(umentation)?

LXF: I was talking to James Turnbull earlier (see interview LXF251) about the importance of documentation. A lot of our readers are pretty critical about incorrect, indecipherable or nonexistent docs for various projects.

Dr: You really do need it. We’ve been trying to design our interfaces so that they guide you and you can find what you need in place. But people just give up, they go to the Google to find the answers – and the answers are there because someone wrote it down. My theory is, if it’s not documented it doesn’t exist or it doesn’t work. Because if you haven’t got to that level of sophistication, people won’t know how to use it, or they’ll use it incorrectly and then they’ll hate the product. So the challenge is to find the medium for how to present the documentation, then people will study it. Because people do not read manuals – they do search though. On the Yocto Project one thing we did, which was kind of surprising… from all our documents we made a ‘megadocument’. Turns out what people do is kind of like a local Google: they grab the whole thing and search it for keywords, and that’s how they use it.

So the documentation issue is still there. Unfortunately the funding is a little challenging, and trying to get it to match up with customer experience is kinda hard. But it’s still so necessary. One of the things about Yocto Project is that there’s a lot of documentation behind it. That’s not so much the case for some projects and start-ups, but it’s something we really focussed on: customer experience and really documenting everything we’re doing.