My current employer was sold to me as a "high documentation" place. What it means in practice is that if you're trying to do something there are 5 outdated documents describing the decision making process for how the project was run, and no documents about how to actually use the resulting software. Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a…
I work in medical devices so we have to write a lot of docs. But they all disappear in document management systems where you can't find anything if you don't already know where it is. Are there no document management systems that are actually useful?
"High-documentation" isn't the cure, either. Just write quality software with well-defined interfaces, minimal dependencies and smooth building processes. I want to be able to build the thing without frustration, to start playing with it in order to learn its internals and debug it. Only then can I be comfortable enough to start implementing features and changes.
That’s how I often use documentation - start documenting something, then ask myself “should the code be fixed to avoid the need to document this part? Yes, yes it should”.
A long provisioning instruction became much shorter as a result of automating it by reducing the need to document.
My current employer was sold to me as a "high documentation" place. What it means in practice is that if you're trying to do something there are 5 outdated documents describing the decision making process for how the project was run, and no documents about how to actually use the resulting software. Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a…
Having multiple systems for docs and Slack for follow-up questions is a major red flag. What you’re describing is a billion dollar search product opportunity though. Most orgs don’t have the discipline to have a single source of truth. So you end up with this mess. Run! Or … fix it and then create a company to fix it for all the other orgs with similar data/docs siloes.
High-Documentation is so out of fashion, for all the wrong reasons. If you are designing anything that is intended to last longer than 6 months, documentation is a critical part of the system. Meetings are great for communicating with people here and now, but only writing can communicate with people from the future. When you meet with your current colleagues, spare a thought for your future colleagues who haven’t yet…
Writing is definitely a critical skill for software development. At my last "staff+" job, I spent most of the time writing documents that seemingly nobody ever actually read. I also reviewed a bunch of them.
What is an example of that working? Just code that speaks for itself? How would you ever know why something was done?
Turn around and ask. For small teams it might work well. Larger teams require more overhead, hence why hiring more people does not produce linear productivity growth.
Read an amazon 6 pager... then try to write one, about anything. and then invite all of your co-workers to pick apart every single line of your document.
I wish more people adopted Andy Grove's thoughts on meetings. https://jondouglas.dev/lets-not-meet/ This company seems to "get it" though. We ought to protect our attention more often. I'd take documentation over no documentation any day. Even if it's 4 years old and was last updated by a person who left for a competitor.
I read through your link and it rang hollow to me. Care to share your insight?
My blog is the insight. The book I recommend may give more context as to why it is important.
My current employer was sold to me as a "high documentation" place. What it means in practice is that if you're trying to do something there are 5 outdated documents describing the decision making process for how the project was run, and no documents about how to actually use the resulting software. Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a…
I work in medical devices so we have to write a lot of docs. But they all disappear in document management systems where you can't find anything if you don't already know where it is. Are there no document management systems that are actually useful?
git works for us across business/electronics/electrical/mechanical/software.
The exception is daily supply chain and accounting, which due to factors like urgency, multiple stakeholders per order, high pace of handover, external system integration, multilingual presentation requirements and nontechnical users we prefer a dedicated web based system with more of a real time focus with event hooks (eg. notification, translation, verification).
doesn't Amazon have a similar structure, tho? i don't know what it's actually like to work there (anyone who does feel free to chime in) but i've interviewed and from what I can tell they put a heavy emphasis on documentation. it's tough to find a bigger and more siloed company than Amazon, and it seems to work for them.
Amazon is high documentation, high meetings culture. The documentation is reviewed by peers, bar raisers, and leaders in a process called document read before being official. Edit: Someone asked for more detail on high meeting culture. There are constant meetings between cross-functional teams, various leadership stakeholders, and ongoing operational planning. That is not including your day to day meetings within you…
Sure, but oftentimes technical documentation is severely lacking. PRFAQs, initial design docs, etc. are thoughtfully created and thoroughly reviewed, but the actual implementation lacks the documentation required to make onboarding (be it new team members or new dependent teams) as smooth as it could be. My favorite is finding an out of date Wiki page from 6 years ago that contains a partial list of API method names, descriptions if you're lucky, and then nothing else, not even a link to the service's AAA page/etc. or a high-level summary of what the service _does_ or _why_. With how many moving parts there are and how inaccessible non-platform-level documentation is, the new hire experience at Amazon can be rather daunting. Even SDE1/2s that are a year in often have a very incomplete picture of what's going on in their own domain space. Too much tribal knowledge.
doesn't Amazon have a similar structure, tho? i don't know what it's actually like to work there (anyone who does feel free to chime in) but i've interviewed and from what I can tell they put a heavy emphasis on documentation. it's tough to find a bigger and more siloed company than Amazon, and it seems to work for them.
Amazon is high documentation, high meetings culture. The documentation is reviewed by peers, bar raisers, and leaders in a process called document read before being official. Edit: Someone asked for more detail on high meeting culture. There are constant meetings between cross-functional teams, various leadership stakeholders, and ongoing operational planning. That is not including your day to day meetings within you…
this statement needs some detail, "high meetings" is obscuring that meetings use the docs (not meetings with no agenda or lots of presentations). meeying use docs as the primary driver, be that a narrative or analysis of a dataset