6 ms·

Write write write and keep writing. Then expect to do 10x as much reading. It's exhausting and definitely relies heavily on employees' writing and reading compr

Write write write and keep writing. Then expect to do 10x as much reading. It's exhausting and definitely relies heavily on employees' writing and reading comprehension skills. HashiCorp produces a mind boggling amount of prose (non-code text). Every employee can read every RFC going back to the first sketch of terraform which was completely rewritten in a second revision. Mailing lists are alive and well. PR descriptions and discussions are often longer than the code being changed. No other company I've worked at has had this dedication to recording decisions, and all of them have struggled heavily with losing institutional knowledge. HashiCorp isn't perfect, but I want all future employers to at least pretend they're remote-first as that seems to be the forcing function for writing everything down. Update: while writing skills are helpful they're definitely secondary to just ensuring knowledge is splatted down somewhere in some form. Perfect is absolutely the enemy of good enough, and I'd rather struggle to gleen knowledge from an unformatted readme in a deep dark corner than have nothing at all.

herval 7y ago
How do/could you quantify the benefits of this culture? I frequently manage groups of “move fast & break things” folks, and RFCs/design docs/etc are a very hard sell (in particular when teams are fully local)
- mlthoughts2018 7y ago
  Over the years my perspective on this shifted a lot. I now feel it’s not worth it to convince people of the need for RFC / design spec process to ensure alignment prior to implementation. If you’re working with people who don’t agree with that process, just leave. That engineering culture is bad and you’re not going to get anywhere. People will use the empty excuse that careful design docs slow them down too much to convert it into a political debate, and try to make the burden of proof on the person asking for alignment prior to resource committal, burying _you_ in bureaucratic doc writing to avoid writing self-evidently more appropriate design docs themselves. The idea of changing this kind of culture is a fantasy and you’ll just burn yourself out. Just leave and don’t work for places like that. Don’t hire people like that.
- schmichael 7y ago
  Quantifying human processes is not one of my strengths, however these are some situations a culture of writing helps avoid: - Fear to go on vacation or take sick days because you'll miss live decision making - Paternity/Maternity or other extended leave requiring a second onboarding upon return - Animosity when left out of a lunch or beer where a design was discussed or decision was made - Cabals of knowledge holders weaponizing their knowledge for job security or advancement - Onboarding is a huge drain on existing workers as all knowledge must be shared 1:1 synchronously. Discourages team growth. - Bias toward risk takers and the loudest voices. Difficult for thorough and thoughtful team members to be effective. If none of these things apply to you, great! I don't want to presume there's one best way of operating.
  - rtx 7y ago
    Do you write about or teach these things.
    - schmichael 7y ago
      Ironically: no. It's something we discuss regularly at HashiCorp and, as you might expect, have a lot of internal resources (docs, videos, training) around. I haven't looked at it myself, but I know Google just released some training materials for technical writing: https://developers.google.com/tech-writing https://developers.google.com/tech-writing
- matwood 7y ago
  Typically the move fast and break things culture also means lots of smaller changes. Scale back the documentation to fit those smaller changes so it does not seem so daunting (RFCs may be overkill). The biggest immediate benefit during onboarding. A new hire can review all the broken paths that have already been tried. Second related benefit is existing employees can go back and look up the details on what was tried and why it didn't work. A prior broken solution may become feasible as assumptions/business/etc... change.
closeparen 7y ago
It’s demoralizing to write write write when you know no one is going to read, and if you link them something more than 100 words long they’ll ask for a meeting instead.
- schmichael 7y ago
  Fair. I find writing a useful exercise even if no one ever reads it (although processes should enforce someone reads it; like a PR). Calling a meeting anyway is great! You have a document to reference to guide the meeting, answer questions, and scribe discussions/decisions! If your worst case scenario is that your technical document becomes a glorified meeting agenda, that's not so bad. Also remember that documents live ~forever, so even if you get no immediate response: write for your replacement 5 years from now who has to figure out wtf you were thinking. :)
- asdff 7y ago
  But occasionally you find yourself years later giving your own thoughts a read read read, and it's helpful that you've taken the time to write write write. Future you will thank you. I'm pretty happy with past me for obsessively documenting some things.
- ahaferburg 7y ago
  Read the document to them aloud, word by word, in the meeting.

herval 7y ago

How do/could you quantify the benefits of this culture? I frequently manage groups of “move fast & break things” folks, and RFCs/design docs/etc are a very hard sell (in particular when teams are fully local)

mlthoughts2018 7y ago
Over the years my perspective on this shifted a lot. I now feel it’s not worth it to convince people of the need for RFC / design spec process to ensure alignment prior to implementation. If you’re working with people who don’t agree with that process, just leave. That engineering culture is bad and you’re not going to get anywhere. People will use the empty excuse that careful design docs slow them down too much to convert it into a political debate, and try to make the burden of proof on the person asking for alignment prior to resource committal, burying _you_ in bureaucratic doc writing to avoid writing self-evidently more appropriate design docs themselves. The idea of changing this kind of culture is a fantasy and you’ll just burn yourself out. Just leave and don’t work for places like that. Don’t hire people like that.
schmichael 7y ago
Quantifying human processes is not one of my strengths, however these are some situations a culture of writing helps avoid: - Fear to go on vacation or take sick days because you'll miss live decision making - Paternity/Maternity or other extended leave requiring a second onboarding upon return - Animosity when left out of a lunch or beer where a design was discussed or decision was made - Cabals of knowledge holders weaponizing their knowledge for job security or advancement - Onboarding is a huge drain on existing workers as all knowledge must be shared 1:1 synchronously. Discourages team growth. - Bias toward risk takers and the loudest voices. Difficult for thorough and thoughtful team members to be effective. If none of these things apply to you, great! I don't want to presume there's one best way of operating.
- rtx 7y ago
  Do you write about or teach these things.
  - schmichael 7y ago
    Ironically: no. It's something we discuss regularly at HashiCorp and, as you might expect, have a lot of internal resources (docs, videos, training) around. I haven't looked at it myself, but I know Google just released some training materials for technical writing: https://developers.google.com/tech-writing https://developers.google.com/tech-writing
matwood 7y ago
Typically the move fast and break things culture also means lots of smaller changes. Scale back the documentation to fit those smaller changes so it does not seem so daunting (RFCs may be overkill). The biggest immediate benefit during onboarding. A new hire can review all the broken paths that have already been tried. Second related benefit is existing employees can go back and look up the details on what was tried and why it didn't work. A prior broken solution may become feasible as assumptions/business/etc... change.

closeparen 7y ago

It’s demoralizing to write write write when you know no one is going to read, and if you link them something more than 100 words long they’ll ask for a meeting instead.

schmichael 7y ago
Fair. I find writing a useful exercise even if no one ever reads it (although processes should enforce someone reads it; like a PR). Calling a meeting anyway is great! You have a document to reference to guide the meeting, answer questions, and scribe discussions/decisions! If your worst case scenario is that your technical document becomes a glorified meeting agenda, that's not so bad. Also remember that documents live ~forever, so even if you get no immediate response: write for your replacement 5 years from now who has to figure out wtf you were thinking. :)
asdff 7y ago
But occasionally you find yourself years later giving your own thoughts a read read read, and it's helpful that you've taken the time to write write write. Future you will thank you. I'm pretty happy with past me for obsessively documenting some things.
ahaferburg 7y ago
Read the document to them aloud, word by word, in the meeting.