Writing, technically(signalsandthreads.com) |
Writing, technically(signalsandthreads.com) |
> 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
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.
But yeah at the end of the day, there is no easy fix, it has to be in the core list of responsibilities of each job to work at the company scale
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.
More information available here: https://www.youtube.com/watch?v=EnB8GtPuauw
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.
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.