I was hoping an explanation for why the documentation was bad, but this just seems to be reasons for why there isn’t enough of it. I thought the problem was that even when we write a lot of documentation, it’s still bad.
In Mercurial we strive to write the shortest but most informative documentation possible. Our idea is that if it’s long nobody will read it, so it’s quite the art to cram all the useful information into the fewest bytes possible. I’m not sure if this is working or not, since people still seem to praise git’s documentation over our own.
Recording someone writing software is not ‘documentation’. Nevermind that video documentation is horrible for anything more than a quick demo. Video, as opposed to text, is not easily indexable.
Given the author’s job, and the plug in the last paragraph, I’m kinda suspicious that this is anything more than content marketing.
The points for “why devs don’t document” are actually decent, but then the crack pipe lights up and the solution is “Hey let’s just record devs writing undocumented code in real time so future devs can look on in despair! ship it!”.
I hate watching videos to learn something, honestly. I can read quite well and absorb more knowledge when reading than listening or watching some one. That’s why I always took notes in school, so I could read over what I took in audibly.
It’s not very clear what this article is talking about. Is it talking about end user documentation, like a user guide? Or is it talking about documenting the architecture and design of s system?
I don’t see how a video of the developer writing code will solve either of those.
writing code gives you positive feedback right away: when it works
writing documentation gives you positive feedback never
so you get a very unsatisfied feeling when you write documentation, it’s like waiting for people that you don’t know when they will arrive, maybe they won’t come at all.
Development and Writing Are Two Different Skillsets
So this is true, but one thing I’ve had to learn the hard way is that writing documentation is a different skill again. I like to think I’m pretty decent at both development and writing, but I still really struggle to write good documentation. There’s a whole set of difficulties about knowing how to organise things, understanding what’s obvious to people and what’s not, etc. that are very different from when you’re writing an article.
This sounds like “we have to check a box, but we don’t care if the solution helps” and “coding über alles”.
Text is good. It’s one of the rare media humans can skim. I can gloss over a class description and find out what I am interested in (the general description, the methods, the particular method I’m searching, etc.). It is non-linear and not bound to time.
It can be well indexed - however far audio indexing will go, it will always be less good then text (because it will most likely transform to text first).
Here’s the thing that rubs me about documentation: the tooling is awfully bad. It’s basically just renderers with some linking between stuff. But the whole text is far less covered then the code. Almost no linters, no style checkers, no way to find out if a certain piece of documentation refers to something that just changed in the last release. We don’t really connect the documentation to the artifact it documents. That makes for a whole lot of inaccuracies and errors, which sometimes might lead to the feeling that no docs is better then outdated docs.
Finally: if your developer is not interested in writing docs, make up your mind about whether thats acceptable for you. If not, tell them what they are paid for. Coders get far too much slack. </rant>
I was hoping an explanation for why the documentation was bad, but this just seems to be reasons for why there isn’t enough of it. I thought the problem was that even when we write a lot of documentation, it’s still bad.
In Mercurial we strive to write the shortest but most informative documentation possible. Our idea is that if it’s long nobody will read it, so it’s quite the art to cram all the useful information into the fewest bytes possible. I’m not sure if this is working or not, since people still seem to praise git’s documentation over our own.
Recording someone writing software is not ‘documentation’. Nevermind that video documentation is horrible for anything more than a quick demo. Video, as opposed to text, is not easily indexable.
Given the author’s job, and the plug in the last paragraph, I’m kinda suspicious that this is anything more than content marketing.
The points for “why devs don’t document” are actually decent, but then the crack pipe lights up and the solution is “Hey let’s just record devs writing undocumented code in real time so future devs can look on in despair! ship it!”.
First thing I thought was ad.
This is definitely an ad disguised as an article. It doesn’t say anything new or present any real solutions other than “Buy my product!”
I hate watching videos to learn something, honestly. I can read quite well and absorb more knowledge when reading than listening or watching some one. That’s why I always took notes in school, so I could read over what I took in audibly.
It’s not very clear what this article is talking about. Is it talking about end user documentation, like a user guide? Or is it talking about documenting the architecture and design of s system?
I don’t see how a video of the developer writing code will solve either of those.
writing code gives you positive feedback right away: when it works
writing documentation gives you positive feedback never
so you get a very unsatisfied feeling when you write documentation, it’s like waiting for people that you don’t know when they will arrive, maybe they won’t come at all.
So this is true, but one thing I’ve had to learn the hard way is that writing documentation is a different skill again. I like to think I’m pretty decent at both development and writing, but I still really struggle to write good documentation. There’s a whole set of difficulties about knowing how to organise things, understanding what’s obvious to people and what’s not, etc. that are very different from when you’re writing an article.
This sounds like “we have to check a box, but we don’t care if the solution helps” and “coding über alles”.
Text is good. It’s one of the rare media humans can skim. I can gloss over a class description and find out what I am interested in (the general description, the methods, the particular method I’m searching, etc.). It is non-linear and not bound to time.
It can be well indexed - however far audio indexing will go, it will always be less good then text (because it will most likely transform to text first).
Here’s the thing that rubs me about documentation: the tooling is awfully bad. It’s basically just renderers with some linking between stuff. But the whole text is far less covered then the code. Almost no linters, no style checkers, no way to find out if a certain piece of documentation refers to something that just changed in the last release. We don’t really connect the documentation to the artifact it documents. That makes for a whole lot of inaccuracies and errors, which sometimes might lead to the feeling that no docs is better then outdated docs.
Finally: if your developer is not interested in writing docs, make up your mind about whether thats acceptable for you. If not, tell them what they are paid for. Coders get far too much slack.
</rant>Spend more time writing documentation. Learn how to write.