Documentation is King
kennethreitz.org
kennethreitz.org
So far i've learned a few seemingly effective techniques:
1) Occasionally construct some weird sentences, throw grammar out the window for a sentence (any longer doesn't work) and people will recall that whole section of the document, months, even years later. I have no idea why this is so effective, but i'd love to know.
2) State an assumption and have it missing the obvious consideration. Don't make it some intricate detail, it has to be in plain sight even for someone not familiar with the topic. Again, people recall these sections and are happy to suggest how you could improve the document.
3) Never tell anyone you're playing tricks like this, it completely loses its effectiveness when people know what you're doing with the slightly strange documents.
4) Test the recall of others frequently on your text. Probe them and figure out what's easy to remember and what's not. You can use this to tweak your documents for future.
5) Don't over use it. The goal doesn't have to be to have them remember everything, but it must allow them to remember where they found the information previously.
YMMV, but i'm blown away so far and i haven't seen anyone talking about this along similar lines yet. It all started after reading one too many psychology books.
Similarly, there's some research that less-legible text is recalled better: http://bps-research-digest.blogspot.com/2010/12/harder-to-re...
Compare also bloggers who intentionally oversimplify and make small errors in their headlines/articles, guaranteeing more attention via outrage-forwarding, a vibrant comment section, and 'hook' for a followup post that extends/clarifies/apologizes.
Strightforwardness is good for many things... but not memorability.
It's my opinion that it should just be part of the developer's discipline to update documentation as they update code, but this seems not to be practical when not everyone shares my idealism for documentation. What ways are there to get buy in from those that need to be convinced about the value of documentation?
Works for us. Most people not up to it I.e. find it boring or can't put a sentence together bail in a month because they can't get their code through the review cycle. They are made well aware of the requirements at interview time.
We're in financial sector so sound engineering and documentation stops us getting in deep shit.
Case in point recently, one of our service providers broke their service API silently. We had their documentation, contracts etc set in stone in source control, named and dated as were our integration paths. When they pointed the finger at us, we were covered.
The small detail was recorded (1 penny rounding method) which meant we could trace it instantly, pop open our log4j dumps and found that they sent the value wrong. Not only that, we raised it to start with because our constraints were documented and assertions were in place.
Programmers should realise that the documentation is just as important (if not more so) than the code itself. If people don't know how to use your wonderful API, then it's useless.
If your comments don't accurately reflect the current code, then either the comments are wrong, or your code is: it's dangerous to have outdated comments in the code - somebody may come along, read the comments, and 'correct' the code because the code didn't do what the comments described it as doing.
Documentation and code can, and surely will, diverge from one another, leading to all kinds of nasty misunderstanding. As long as there aren't any reasonable† tools for keeping them in sync, it's best to avoid the problem altogether.
IMHO it's good practice to have separate `implementation' (mostly code and static data) and `businesse requirements' (mostly documentation). Minimize overlap, strive for singular responsibility: it should be clear whether a particular change should go into documentation (change in requirements) or into implementation (to match the requirements).
Tangentially related, if you have a habit of using `git blame' (or equivalent in your SCM), commit comments are good place to mention changes in business requirements, especially small ones.
† nope, UML is not an aid here.
maybe the answer is in the middle and above, great tool makers are great docs writer.
Being "not surprised" seem to be the new meme on HN. Anyway, let me disagree: when you know how to write words in a sentence, you do it well under any circumstances. (I forgot its name but there is a story of this British poet whose one-sentence instruction sticker on how to handle the toilet flush was such a precise and cristalline piece of prose)
So no, if academic papers are so poorly written now compared to manpages or academic papers centuries ago, it is because academic people are worse writers.
We should propose how to implement that feature, (spec) get some feedback, go do it, review the implementation against the spec and even then I would want to have a sort of stack overflow Q&A site so people can ask why did you do that ?
Anyone else feel we are missing a whole boatload of tricks?
What's this? Why is this here? Why do I want it? Why is this good? Why do I care? Why? What's that mean? What's this knob do? What's that code do? Why is this code here? Why?
Flabby documentation, user documentation written in programmer jargon and scatter-shot code comments are all comparatively easy to write. When somebody bothers to write that.
Writing for the end-user (whoever that might be) is tougher, and I find require iterating on the content of the documentation, UI, release notes, comments, or whatever. Writing less documentation or fewer comments — while conveying the necessary details — is hard work.
Note, this is not to say that documentation doesn't matter. It definitely has a prominent role. So does "does the job." Preferably well. The blogger mentions a prime lens works because it doesn't allow zoom. Sure it does, you just have to move your feet. This can actually be rather annoying when you are trying to get a candid shot in the house. Framing doesn't automatically happen with a prime lens, that is. However, the quality of image from a prime is huge. More than makes up for the short comings for many of us.
More documentation is not necessarily better. Just like code, the best documentation is the documentation you never had to write because you found a simpler way, and eliminated the issue completely.