I listened to some of this today and it's really great. Lots of similar learnings as has been had from the g3doc team at Google.
More information available here: https://www.youtube.com/watch?v=EnB8GtPuauw
Writing, technically
11–18 of 18 posts
Re: Writing, technically
#12I think a lot of companies would benefit immensely if they hired a few tech writers. Management always talks about collaboration and knowledge sharing but they refuse to put money behind this desire. Instead it’s up to the workers to create documentation while also having to finish project deadlines. And most developers don’t really enjoy writing or are good at it.
Re: Writing, technically
#13I think a lot of companies would benefit immensely if they hired a few tech writers. Management always talks about collaboration and knowledge sharing but they refuse to put money behind this desire. Instead it’s up to the workers to create documentation while also having to finish project deadlines. And most developers don’t really enjoy writing or are good at it.
TWs help for sure but the ones with the ones with the most impact don't try to do it all themselves, and instead make it easier / less painful for everyone in the company (or at least engineers to start) to create documentation. Or they at least raise hell and make it clear that the more everyone takes ownership of docs the more likely it is that the company overall will succeed. To put it another way, a common problem that I see is that company's recognize their docs are terrible and then hire a couple TWs and the engineers say "phew! Now I really don't need to care about documentation at all!" I think part of Stripe's initial success was that everyone supposedly did customer support and that helped them see that good docs was a great way to reduce support burden (rather than providing ad hoc answers, if you have a doc that explains the solution well, you can just link to that instead). That's just conjecture, BTW. I haven't confirmed that idea with Stripe people. Also it's just common sense that if your main product is an API then your documentation is mission critical to overall success. Another scalable approach is for TWs to provide training that helps non-TWs get less intimidated by writing docs.
Re: Writing, technically
#14The intro touches on something I learned to be true very early in my technical writing career, but which isn't discussed much and may not be widely known: > helping to push forward all sorts of efforts around knowledge-sharing at Jane Street As a TW I often find myself advocating for more scalable/sustainable/permanent ways to store institutional knowledge. The classic example is email. Sometimes there is extremely u…
At my day job, they delete email after 180 days. I often wonder how much time has been lost recreating information that was deleted that way.
And how much money might have been saved not having some of that information available later... because that is totally a good reason to burn history.
Re: Writing, technically
#15For those that didn't listen to season 1, I recommend it. Really interesting show.
Re: Writing, technically
#16I think a lot of companies would benefit immensely if they hired a few tech writers. Management always talks about collaboration and knowledge sharing but they refuse to put money behind this desire. Instead it’s up to the workers to create documentation while also having to finish project deadlines. And most developers don’t really enjoy writing or are good at it.
TWs help for sure but the ones with the ones with the most impact don't try to do it all themselves, and instead make it easier / less painful for everyone in the company (or at least engineers to start) to create documentation. Or they at least raise hell and make it clear that the more everyone takes ownership of docs the more likely it is that the company overall will succeed. To put it another way, a common probl…
"make it easier / less painful for everyone in the company (or at least engineers to start) to create documentation. "
Exactly. I am not averse to writing most of the content but at least in my company the documentation processes are very intricate and I really don't want to learn all the details and rules for submitting docs. I have enough to do with wrestling with AWS and feel my time is better spent on that.
Same for booking flights. We used to have somebody who would book flights. That role got eliminated to save costs and now the engineers are burning countless hours figuring out how Concur works and what the latest travel rules are.
It's nice so have support staff that are experts in these systems. And I think it's actually cheaper. there is a reason why the big guys have assistants.
Re: Writing, technically
#17Earlier quoted context omitted.
TWs help for sure but the ones with the ones with the most impact don't try to do it all themselves, and instead make it easier / less painful for everyone in the company (or at least engineers to start) to create documentation. Or they at least raise hell and make it clear that the more everyone takes ownership of docs the more likely it is that the company overall will succeed. To put it another way, a common probl…
"make it easier / less painful for everyone in the company (or at least engineers to start) to create documentation. " Exactly. I am not averse to writing most of the content but at least in my company the documentation processes are very intricate and I really don't want to learn all the details and rules for submitting docs. I have enough to do with wrestling with AWS and feel my time is better spent on that. Same…
We had some success making it easy for engineers.
User documentation was inline with the code (think perldoc/pydoc). Developer documentation (as comments) was also co-located with the relevant code.
This automatically gave us man pages at a shell prompt. We could include those man page outputs in report .zip files that got emailed to users, and push them to our website.
There's an art to keeping this organized. Always having a good trail of breadcrumbs was important, like a comment next to a variable assignment telling the developer to update the user docs if that constant is changed. Also avoiding duplications, which leads to drift/inaccuracy. We considered inaccurate documentation to be a bug. Full time employees took to this. Contractors often needed reminding.
As the project grew there was managerial pressures to get involved in other stuff like power points and sharepoint.
Re: Writing, technically
#18Earlier quoted context omitted.
"make it easier / less painful for everyone in the company (or at least engineers to start) to create documentation. " Exactly. I am not averse to writing most of the content but at least in my company the documentation processes are very intricate and I really don't want to learn all the details and rules for submitting docs. I have enough to do with wrestling with AWS and feel my time is better spent on that. Same…
We had some success making it easy for engineers. User documentation was inline with the code (think perldoc/pydoc). Developer documentation (as comments) was also co-located with the relevant code. This automatically gave us man pages at a shell prompt. We could include those man page outputs in report .zip files that got emailed to users, and push them to our website. There's an art to keeping this organized. Alway…
I have seen several of such initiatives. They all started out well but then slowly died because management didn’t allocate long term attention, time and budget. If this is not part of the fundamental company process it will die slowly.