Writing, technically

[kaycebasques]

The 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 useful knowledge buried in an email thread. I often work with engineers (or whoever) to turn that knowledge into publicly searchable documentation.

P.S. tangentially related to the title of this post, my brother came up with a fun self-deprecating joke (which I later used on as a tagline [1])

> Technically, I'm a writer

[1] https://developer.chrome.com/blog/welcome/

[nicbou]

Same. Unless you make it your personal responsibility, it won't get done. Documentation is hard, and not everyone's definition of fun. It's especially hard to explain things you are intimately familiar with to your colleagues.

I've done that for long enough to be very good at it. Now I earn my living from documenting stuff the local government doesn't document property.

[macintux]

Every company I work for struggles with knowledge capture/sharing, and it’s always a priority, but never really prioritized. Tough nut to crack.

[Zababa]

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.

[dSebastien]

So true.

People don't realize and/or don't care much about all the information that gets lost in e-mail.

I've been struggling for years to push people to document stuff. Often I'm the only one who writes page after page, and send links to docs, until there are hundreds. At that point, others usually start to chime in a bit.

[gravypod]

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

[spaetzleesser]

I 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.

[kaycebasques]

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.

[ta988]

For those that didn't listen to season 1, I recommend it. Really interesting show.

[kobyconrad]

This is so helpful