4 ms·
I think the reality is regardless of what we want, that at most companies the people who write docs are the people who write code. That doesn't mean it's the be
by Grimm1 5y ago
I think the reality is regardless of what we want, that at most companies the people who write docs are the people who write code. That doesn't mean it's the best way but it does make it the way we have to deal with a majority of time. That's why building tools to help engineers be better documenters from high level through to the low level is I think in the interest of everyone.
In my last company before I jumped, I architected and implemented our full data infrastructure along with one other engineer. Which means I was responsible for high level conceptual documentation and low level documentation all the same and while I've written documentation before and for years I'm not formally trained in it so it was all still basically winging it. Since then I've actually taken a few short courses on writing better technical documentation since I felt it was a weak spot and having tools to assist in making that easier would have been great.
Documentation is hard and has been neglected but man does it have major underlying costs to getting it wrong.
Everything from on boarding being slow to misunderstandings that cause expensive bugs and everything in between. The root cause is developers have a hard time understanding complex systems and we as an industry are really hit and miss on writing the documentation that would make that understanding easier.
- woutgaze 5y agoCan you recommend a book or course for improving ones ability to write good technical documentation?
- cratermoon 5y agoNot the parent poster but I can recommend some books - The Craft of Scientific Writing, Michael Alley - The Craft of Editing, Michael Alley - A Guide to Writing as an Engineer, David Beer and David McMurrey - On Writing Well, William Zinsser There's also a plethora of stuff on the web, as you might imagine, too much to go into it all, but McMurrey has a website https://www.prismnet.com/~hcexres/textbook/acctoc.html https://www.prismnet.com/~hcexres/textbook/acctoc.html
- spockz 5y agoCan you please share the lessons learned in the courses about writing documentation or perhaps recommend some courses/materials? At my place we have an eternal struggle in “level”. We have some very high over docs, then ADR for specific decisions. At the lowest level we have the api documentation which we find most people don’t read. And then we have some tutorials. Every time I read our documentation it feels very inadequate of conveying all our knowledge and intentions.
- Grimm1 5y agoI think it may just be easier to share where I got any of my lessons from. https://developers.google.com/tech-writing https://developers.google.com/tech-writing Google has two short courses about 6 hours total or so that seemed a good consistent basis for me as an engineer writing documentation. I'm not sure if it's going to answer your question on what types of documentation you will need though and how to make it feel less inadequate just how you as an individual can write better documentation.