5 ms·

Tools for a Culture of Writing (2021)

123 points by k_sze 4y ago

rchaves 4y ago
One point I struggle with is when to write a decision record. There are many decisions that go through without us even realizing it was a decision, sometimes it was just a reply to a comment, or something said on a meeting, which you put on the code and boom, a decision, usually logged only on the “why” of a commit message What would be the rule of thumb, which decision size is big enough to worth a DR, what triggers “I have to write a DR for this”?
- jordanbeiber 4y ago
  We’ve started to do this when it comes to stuff that is architechtural significant, for example team A decides to event-source foo. Or team B opts to write microservices. Also - anything infosec related goes through an ADR process. Rule of thumb: are we, or someone else, going to second guess this decision in a year or two? If it feels likely an ADR is in place.
- patrck 4y ago
  Do you keep an engineering log for yourself? If not, then start one as that's the easiest way to review what the concerns of the day were back then, and to begin to see where having history starts paying dividends. Otherwise, something like the principle of https://en.m.wikipedia.org/wiki/Prudent_man_rule https://en.m.wikipedia.org/wiki/Prudent_man_rule -- ie. were you parachuted into this project, which decisions would need rationales?
- creakingstairs 4y ago
  Anything that is related to "why" related to _changes in_ architecture and domain usually goes in for me. e.g. - Why did we end up not using FIFO queues here? - Why did we decide to disable users who did x? - Why did we create a new module rather than updating the existing one? I say "changes in" because we'd often write an architecture document at the start of a project. That document has the initial assumptions and reasonings. A decision record documents inevitable changes to the plan as we find out more about the problem space. I also find having a person directly responsible updating the record is the best, if the project doesn't involve too many people.
- dllthomas 4y ago
  In talking to my team, my advice has been "whenever it will be useful", which is of course a bit glib but I don't think we want hard and fast rules. It's going to be more true of things that are harder to change, more true of things that touch more places in the code, more true when decisions are higher risk, more true when reasoning is less obvious. I also think we should err on the side of writing too many ADRs, and writing ADRs that are too lightweight. There's some implicit pressure that if we're writing down our reasoning we'd better make sure it's good reasoning, but it's simultaneously true that some decisions don't deserve a lot of deliberation and when a decision didn't get a lot of deliberation we would like to know that down the line. If we capture some number of ADRs that say "decided XYZ because shrug", then down the line when we're inevitably bit by some bad decisions, we can look at whether those were disproportionately the ADRs that got less thought.
patrck 4y ago
This needs a prefatory "Tools for a Culture of Reading". How many colleagues will do a literature review before starting something? How many will take notes and try to understand the history of how everything got to be the way things are? RFCs and docs are great; it just seems like they're usually secondary to the functional docs of throwing code over the progressively higher walls of git-hooks, build tests, and ops monitoring.
- deleted 4y ago
  [deleted]
- nonrandomstring 4y ago
  Or maybe "tools for promoting a culture of writing". Increasingly I find I may be in a "minority of writers" in org teams who are primarily visual, memetic, kinetic and leave only fragmented records in mixed medias. I've also encountered younger engineers/programmers who pretty much cannot type! (only thumbs on a phone screen) - not even hunt and peck... just staring at the keyboard like it's an alien technology. I actually understand this way of being. Using a visual programming language like PureData/LabView (dragging cords) and interacting via sliders, visual indicators/meters all day long I've inhabited the zone where I have been solving hard DSP problems in a visual-kinetic way, and hardly "thought in language" for hours on end. If someone comes into the workshop and asks me a verbal question it takes a few seconds to reboot that part of my head in order to speak. But what I notice is that this mode of being in the world (Dasein?), is becoming dominant as people wander around all day, smartphones in hand (I don't use them), and so there's fewer moments when people process what they are doing/thinking qua language. So for example; As desktop person who spends a good deal of the day interfacing to the world through a full keyboard and screen my fingers and textual brain are engaged, but some colleagues may do things like send a photo of a schematic taken on their phone, no accompanying text or explanation, not even a relevant subject line. So I get that they are not "thinking" in language. I wonder if I am part of a shrinking/dying culture of symbolic communicators.
  - nottorp 4y ago
    I've worked with a guy who simply could not understand what he had to do if told in writing... email, IM whatever. When you told him in conversation he got it and did decent (not brilliant) work. He was a programmer. You'd think writing code all day would allow you to understand writing...
stonecharioteer 4y ago
I write copious documentation for everything I touch. My colleagues do not bother to read them, nor do they try to learn from my practices. I continue to do so, everywhere I go, because I design my applications by writing documentation first, or alongside my code. It helps me think. I do not think that tools are necessarily the problem. I use README.md files mostly after trying to use Sphinx and Notion. This has a very low entry point. But they do not care. They insist on using one time hacks and never documenting things, even Root Cause Analyses. Like others have said here, we need ways to improve and build a culture of reading and writing documentation. Our CTO says he wants to build this, but there's some disconnect.
- maroon-ranger 4y ago
  Any ideas on how one might “build a culture of reading and writing documentation”?
- titanomachy 4y ago
  If you don't have the skills, power, or desire to improve the culture where you work, and it consistently bothers you, then go work somewhere that's already closer to what you want. Amazon and Google are good examples of companies that make heavy use of written design documentation and post-mortems.
gilbetron 4y ago
Writing is pretty easy, reading is the hard part. Between the ridiculous amount needed to read, plus the fact that maintaining up-to-date information is really difficult and how that makes reading even worse ("Should I bother reading this when it is out of date, or just talk to the person that has it all in their head?"). Written works have an over-exaggerated finality to them. They can be good for capturing some of the reasoning behind a decision, but even then, it is only somewhat spotty.
- dllthomas 4y ago
  I've been liking ADRs with cross-references that are checked in CI and surfaced in code review.
- resonious 4y ago
  I'll agree that reading is hard, but I think it's also fair to say that reading good writing is easier. Then, we can say that it's hard to write well, and it follows that reading most writing is hard (including this comment probably...)
coffeefirst 4y ago
The premise is wrong. The hard part isn’t the structure or purpose of the documents, you can do an ad hoc structure and just strive to be clear. The hard part is the library. How do you organize all these records so they might be usable by someone two years later.
- shakezula 4y ago
  Notion has worked okay for us in the past, but recently we’ve moved to just using markdown documents in Git. It’s just as searchable, and stays closer to the code. RFCs et al. are submitted as PRs.
  - titanomachy 4y ago
    I can heartily recommend Obsidian[0] as a way to augment "markdown documents in Git". It lets you cross-reference between your markdown documents using [[wiki links]] so you can start building a knowledge graph. [0]: https://obsidian.md/ https://obsidian.md/
    - shakezula 4y ago
      I am already an avid Obsidian user but I absolutely encourage the promotion of it. It’s one of the first apps I install on any fresh machine.
- dllthomas 4y ago
  I find cross-references to be a big win. I've taken to using `@@{subject}` syntax as anchors and `^^{subject}` as references, anywhere in comments, docs, etc, within a single repository. Then I set up tooling that checks that every reference has a (single) corresponding anchor, and tooling that surfaces in github PRs the other relevant bits when an anchor or reference shows up in the (changed or context) lines of a diff.

123 points by k_sze 4y ago

One point I struggle with is when to write a decision record. There are many decisions that go through without us even realizing it was a decision, sometimes it was just a reply to a comment, or something said on a meeting, which you put on the code and boom, a decision, usually logged only on the “why” of a commit message What would be the rule of thumb, which decision size is big enough to worth a DR, what triggers “I have to write a DR for this”?

jordanbeiber 4y ago
We’ve started to do this when it comes to stuff that is architechtural significant, for example team A decides to event-source foo. Or team B opts to write microservices. Also - anything infosec related goes through an ADR process. Rule of thumb: are we, or someone else, going to second guess this decision in a year or two? If it feels likely an ADR is in place.
patrck 4y ago
Do you keep an engineering log for yourself? If not, then start one as that's the easiest way to review what the concerns of the day were back then, and to begin to see where having history starts paying dividends. Otherwise, something like the principle of https://en.m.wikipedia.org/wiki/Prudent_man_rule https://en.m.wikipedia.org/wiki/Prudent_man_rule -- ie. were you parachuted into this project, which decisions would need rationales?
creakingstairs 4y ago
Anything that is related to "why" related to _changes in_ architecture and domain usually goes in for me. e.g. - Why did we end up not using FIFO queues here? - Why did we decide to disable users who did x? - Why did we create a new module rather than updating the existing one? I say "changes in" because we'd often write an architecture document at the start of a project. That document has the initial assumptions and reasonings. A decision record documents inevitable changes to the plan as we find out more about the problem space. I also find having a person directly responsible updating the record is the best, if the project doesn't involve too many people.
dllthomas 4y ago
In talking to my team, my advice has been "whenever it will be useful", which is of course a bit glib but I don't think we want hard and fast rules. It's going to be more true of things that are harder to change, more true of things that touch more places in the code, more true when decisions are higher risk, more true when reasoning is less obvious. I also think we should err on the side of writing too many ADRs, and writing ADRs that are too lightweight. There's some implicit pressure that if we're writing down our reasoning we'd better make sure it's good reasoning, but it's simultaneously true that some decisions don't deserve a lot of deliberation and when a decision didn't get a lot of deliberation we would like to know that down the line. If we capture some number of ADRs that say "decided XYZ because shrug", then down the line when we're inevitably bit by some bad decisions, we can look at whether those were disproportionately the ADRs that got less thought.

patrck 4y ago

This needs a prefatory "Tools for a Culture of Reading". How many colleagues will do a literature review before starting something? How many will take notes and try to understand the history of how everything got to be the way things are? RFCs and docs are great; it just seems like they're usually secondary to the functional docs of throwing code over the progressively higher walls of git-hooks, build tests, and ops monitoring.

deleted 4y ago
[deleted]
nonrandomstring 4y ago
Or maybe "tools for promoting a culture of writing". Increasingly I find I may be in a "minority of writers" in org teams who are primarily visual, memetic, kinetic and leave only fragmented records in mixed medias. I've also encountered younger engineers/programmers who pretty much cannot type! (only thumbs on a phone screen) - not even hunt and peck... just staring at the keyboard like it's an alien technology. I actually understand this way of being. Using a visual programming language like PureData/LabView (dragging cords) and interacting via sliders, visual indicators/meters all day long I've inhabited the zone where I have been solving hard DSP problems in a visual-kinetic way, and hardly "thought in language" for hours on end. If someone comes into the workshop and asks me a verbal question it takes a few seconds to reboot that part of my head in order to speak. But what I notice is that this mode of being in the world (Dasein?), is becoming dominant as people wander around all day, smartphones in hand (I don't use them), and so there's fewer moments when people process what they are doing/thinking qua language. So for example; As desktop person who spends a good deal of the day interfacing to the world through a full keyboard and screen my fingers and textual brain are engaged, but some colleagues may do things like send a photo of a schematic taken on their phone, no accompanying text or explanation, not even a relevant subject line. So I get that they are not "thinking" in language. I wonder if I am part of a shrinking/dying culture of symbolic communicators.
- nottorp 4y ago
  I've worked with a guy who simply could not understand what he had to do if told in writing... email, IM whatever. When you told him in conversation he got it and did decent (not brilliant) work. He was a programmer. You'd think writing code all day would allow you to understand writing...

stonecharioteer 4y ago

I write copious documentation for everything I touch. My colleagues do not bother to read them, nor do they try to learn from my practices. I continue to do so, everywhere I go, because I design my applications by writing documentation first, or alongside my code. It helps me think. I do not think that tools are necessarily the problem. I use README.md files mostly after trying to use Sphinx and Notion. This has a very low entry point. But they do not care. They insist on using one time hacks and never documenting things, even Root Cause Analyses. Like others have said here, we need ways to improve and build a culture of reading and writing documentation. Our CTO says he wants to build this, but there's some disconnect.

maroon-ranger 4y ago
Any ideas on how one might “build a culture of reading and writing documentation”?
titanomachy 4y ago
If you don't have the skills, power, or desire to improve the culture where you work, and it consistently bothers you, then go work somewhere that's already closer to what you want. Amazon and Google are good examples of companies that make heavy use of written design documentation and post-mortems.

gilbetron 4y ago

Writing is pretty easy, reading is the hard part. Between the ridiculous amount needed to read, plus the fact that maintaining up-to-date information is really difficult and how that makes reading even worse ("Should I bother reading this when it is out of date, or just talk to the person that has it all in their head?"). Written works have an over-exaggerated finality to them. They can be good for capturing some of the reasoning behind a decision, but even then, it is only somewhat spotty.

dllthomas 4y ago
I've been liking ADRs with cross-references that are checked in CI and surfaced in code review.
resonious 4y ago
I'll agree that reading is hard, but I think it's also fair to say that reading good writing is easier. Then, we can say that it's hard to write well, and it follows that reading most writing is hard (including this comment probably...)

coffeefirst 4y ago

The premise is wrong. The hard part isn’t the structure or purpose of the documents, you can do an ad hoc structure and just strive to be clear. The hard part is the library. How do you organize all these records so they might be usable by someone two years later.

shakezula 4y ago
Notion has worked okay for us in the past, but recently we’ve moved to just using markdown documents in Git. It’s just as searchable, and stays closer to the code. RFCs et al. are submitted as PRs.
- titanomachy 4y ago
  I can heartily recommend Obsidian[0] as a way to augment "markdown documents in Git". It lets you cross-reference between your markdown documents using [[wiki links]] so you can start building a knowledge graph. [0]: https://obsidian.md/ https://obsidian.md/
  - shakezula 4y ago
    I am already an avid Obsidian user but I absolutely encourage the promotion of it. It’s one of the first apps I install on any fresh machine.
dllthomas 4y ago
I find cross-references to be a big win. I've taken to using `@@{subject}` syntax as anchors and `^^{subject}` as references, anywhere in comments, docs, etc, within a single repository. Then I set up tooling that checks that every reference has a (single) corresponding anchor, and tooling that surfaces in github PRs the other relevant bits when an anchor or reference shows up in the (changed or context) lines of a diff.