3 ms·
I used to feel that way, but now generally don't. Most documentation is effectively duplication of something already expressed in the code. That means that when
by wpietri 10y ago
I used to feel that way, but now generally don't. Most documentation is effectively duplication of something already expressed in the code. That means that whenever you add docs, you are multiplying the effort needed to change things in the future. You also create opportunities for the various expressive duplications to diverge, causing untold confusion.
Now documentation is always a last resort for me. That's a shame, as I enjoy writing. Instead I try to put knowledge in existing places, like unit tests, acceptance tests, method names, object names, code structure, file layout, in-app text, and all of the other little things I'm already doing along the way. Only if I can't put something there will I write docs, and then reluctantly and with a feeling I probably missed a chance to minimize duplication.
The only documentation I still write without reservation is stuff that obviously doesn't have to keep up with the project as it changes. E.g., personal journals and project blogs are great, in that everybody understands those are out of date right after they're written.
- awinter-py 10y agoI agree. Docs/code impedance mismatch is a problem that a docs tool needs to solve to stay relevant. Good docs will resemble or contain a test suite. I agree with your point about blogposts -- publish date is like a sell-by date, makes it clear when the post has gone stale. Getting insiders to read docs is also hard. Not every piece of code is worth documenting. But I think highly critical and highly reused code is worth documenting, in part for programmers and in part so that non-coder stakeholders can understand the details of the product (i.e. 'sell what you make' if they're on the sales team).
- dragonwriter 10y ago> Docs/code impedance mismatch is a problem that a docs tool needs to solve to stay relevant. It's not an impedance mismatch (which results from difference in the structural representations supported by different systems), it's just a content mismatch. And it's not a tooling problem, it's a process problem. Documentation is the single source of truth for intent, and development process must respect that. This becomes more and more important the more people who aren't developers need to understand the logical function of the system.
- enraged_camel 10y agoI don't think the things you listed, even when combined, are sufficient substitutes for well-written documentation. The fact of the matter is that, for humans, plain English is always much easier to understand than computer code. The more complex the code, the more true that is going to be. You can use all the friendly function names and object names and file layouts you want. At the end of the day, it is not going to be enough for someone who is not familiar with that part of the system to understand it quickly and to the appropriate level of detail. This is especially true if you have junior-level or intermediate-level people on your team. It is also true if you ever end up coming back to some piece of code you yourself wrote a year ago. Furthermore, documentation can provide additional value by including examples of code usage in different settings that you may not have covered in your test cases due to not being immediately relevant. It can contain links to other websites and have embedded images of system diagrams or data flow. It can also describe third-party systems your code has to interact with and various bugs and unconventional behavior that may exist in those systems that your code has to account for. Yes, documentation involves more upfront effort. IMO the correct way to deal with that is to include that in project estimates, and to not mark tasks and features to be "done" until their documentation is written. Same with revisions and bug fixes. I understand the feeling that it duplicates logic already expressed in the code. But look at it this way: code is for computers. Documentation is for humans.
- wpietri 10y agoI should be clear that I like good documentation, and will happily write it when necessary. It's just that over the years, I've a) found a lot of ways to make it unnecessary, b) grown to despise useless or out of date docs, which is the bulk of what I see, and c) grown very tired of writing documentation that people end up not reading. > [...] plain English is always much easier to understand than computer code [...] This is especially true if you have junior-level or intermediate-level people on your team. This is why I'm a big fan of collective code ownership, pair programming, and frequent pair rotation. That has a variety of benefits. It also has substantial advantages over documentation. A big piece of which is that the need for documentation is always speculative, whereas answering a question always works from a confirmed need. > It is also true if you ever end up coming back to some piece of code you yourself wrote a year ago. This is what I use tests and journals for. Well-written tests are essentially machine-verifiable documentation. They tell me what the intent of the system is. If I want to know the history of the intent, then I turn to my journals. > But look at it this way: code is for computers. Documentation is for humans. I couldn't disagree more. As Martin Fowler says: “Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” Code and tests are primarily means of communication between developers. They have the constraint that they should result in a running system. But we stuff most of the work of that into compilers, optimizers, and run times. Our tools are -- and should be -- optimized for human productivity. And since programming is mostly a team sport, the biggest value of our tools is in how they enable that teamwork.