Why wouldn't a company choose to have the developers who write the code also write the documentation for that code? Is it not the case that the one...
For further actions, you may consider blocking this person and/or reporting abuse
"cognitive bias of the curse of knowledge or the curse of expertise"
This very true. When I sit down to write documentation for any codebase I work on, I tend to assume that the reader would understand how some things work out of the blue. Which leads to poorly written and incomplete docs.
I agree cognitive bias is huge, which we should do as much as possible to mitigate. Having at least someone of the target audience (besides the developer) check the docs is a must for me. If sharing knowledge is a team/company priority (which I wish it would be at more places), having another person write the docs would be an excellent way to do this.
I'm a big fan of lightly sketching docs before coding because it helps guide my development, and communicate to my team early on. To me, it's the same philosophy as Test Driven Development - you should do it at some point, so instead of it being a chore, treat it as a canvas to guide your coding.
I feel a bigger problem than this, is that I've seen too many teams have little to no docs at all. You then have new members struggle to onboard, old members struggle to maintain, and everyone has to dig their head in the codebase for a long time to make sense of it all. It doesn't scale and is just wasted time.
My philosophy is that communication is key to building great software. And great communication to me happens throughout the dev cycle, is shareable, simple, and can reach a wide audience.
Agree with a lot of this. The only thing I'd add is that there is a difference between internal facing docs, which was not the focus of my post here, and external facing docs for developer users of the product, which was the focus of the blog post.
As I mentioned to another person who commented earlier, the same expectations of creating a documentation journey don't apply, in my opinion, on internal facing docs and certainly not on docs used for docs driven development. Although, there definitely should be some standardization and expectation of quality on them absolutely.
What's your take on the opposite approach? Writing the docs first, as a design document, and the code later, making tweaks to the docs when needed?
I'm a big fan of that approach. Documentation driven development can help the dev team map out exactly the specs they are building against, clarify edge cases, etc., etc. I'd just say that those docs produced in the early stages I'd classify them as internal docs, which don't have the same expectations on them as external documentation, in my opinion.
Interesting take.
Weird, the first thing I would assume is having a developer writing text documents is cost inefficient. Anyway, couldn't it be generated using AI nowadays? 🤓
AI can definitely be a big assist nowadays! It's not sufficient yet still by itself, but maybe that'll change soon? 😅
I wonder how much this can be countered by having external reviews for documentation, and treating it as a key part of the release process.
Who will be doing the reviews for the docs in the release process?
If the reviews mandate technical writers and/or folks trained/experienced in the discipline to be reviewers w/the ability to hold off a merge if it doesn't meet standards, then I think that would be a good approach. I worked somewhere where that was the case, and I think it went pretty well.
Great post
Hm, good priorities, except for one. Write the source/design documentation before the code. The code will be better and the product too. The coder van be anyone skilled enough. The documenter should be able to write and understand the domain. First document, then code!
Both developers and technical writers are key to quality documentation AND usable software, APIs, and so on.
When technical writers work hand in hand with developers before coding begins (or early in the development process) omissions in functionality, poorly named or too similarly named functions, incorrectly typed variables, and so on can be identified and corrected before code goes into production. Additionally, many technical writers are also programmers and can test that examples from their documentation work as expected once the code is live.