6 ms·

Writing docs well: why should a software engineer care?

109 points by azhenley 4y ago

Jensson 4y ago
> The cartoonist Richard Guindon has a famous quote: “writing is nature’s way of letting you know how sloppy your thinking is.” You might have an impression that you understand something well, but that sense of clarity is often an illusion, and when you go to explicitly capture your understanding in a document, you discover that you didn’t understand things as well as you thought. There’s nowhere to hide in your own document. Coding is natures way of showing how sloppy your thinking is, not writing natural language text. It is really easy to hide sloppy thinking behind natural language, otherwise there would be a lot of overlap between great writers and great coders, but there doesn't seem to be much correlation there at all. Coders tend to be precise with their language, but most people prefer to read imprecise sentences so you easily gravitate towards imprecise language if you try to practice writing.
- mrich 4y ago
  And testing is nature's way of telling you how sloppy your code is, I suppose? (recursion intended)
  - Jensson 4y ago
    Yeah, testing shows you that your code is sloppy, writing is even worse since there is no testing at all, even the worst code is better tested than the best text as long as the programmer ran it once.
    - KronisLV 4y ago
      > writing is even worse since there is no testing at all Isn't it possible to get a beta reader? Just someone who will go through your writing and give you feedback? If you are writing docs, a lot of the time you'll also have coworkers there with you, that you'll be able to float the docs to for a quick look, or maybe other people who are interested in your project, if doing open source, or even a friend. It is a bit worse than automated testing, but surely better than nothing! Also, there are apps or sites like this, that help you detect when you have run on sentences or complicated wording: https://hemingwayapp.com/ https://hemingwayapp.com/ Those could sometimes be useful.
- gandalfgreybeer 4y ago
  > Coders tend to be precise with their language, but most people prefer to read imprecise sentences so you easily gravitate towards imprecise language if you try to practice writing. Preferring to read imprecise sentences comes down to what the purpose of the written work is, does it not? Clear and precise technical documentation and even research papers are really helpful and can be practiced. If it’s poetry or a level of emotional buildup such as in fiction is needed, then that’s what people will prefer. Context on what is being written matters.
  - Jensson 4y ago
    In theory yes, in practice documentation tends to be too sloppy to be useful. The problem is that writing all the details is equivalent to just providing the source code, so you need to explain less. But then unless what you are working with has very clean abstractions the documentation becomes worthless because it doesn't explain things well enough. So in practice documentation for a codebase is mostly worthless unless the codebase is very cleanly written, which wont be the case unless we are talking about programming languages or similar. The real documentation people use in codebases is looking at how things are used in other parts of the codebase. Then you have examples and maybe even tests showing how it works, so you start from there and maybe test some things if you need to do things a bit differently. So when is documentation actually useful? When you provide a library that is intended to be used outside of your codebase, so a person who adds the library to his codebase can understand how to use it without having examples to look at in their code. But this is a very specific case and most software engineers don't have to think about it. If I'm missing something here please explain why, but I've never found any documentation to be useful, except for libraries from outside your codebase. And even for libraries it is often easier and faster to just read the source code if it is available. Edit: If you are talking about design documents for services and features then those are useful, yes, but that is usually not what people talk about when they talk about software engineers writing documentation.
    - knighthack 4y ago
      > If I'm missing something here please explain why, but I've never found any documentation to be useful, except for libraries from outside your codebase. And even for libraries it is often easier and faster to just read the source code if it is available. For simple packages, I understand. For anything else, you are committing hyperbolic falsehood if you (or others) claim that it is "easier and faster to just read the source code" and "even for libraries", compared to reading examples/well-written documentation.
- cratermoon 4y ago
  “Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” – Martin Fowler
- olau 4y ago
  I've personally found that to write a good API, you need both code that implements the API and code that uses it, and you also need to write the documentation of that API. The former reveals flaws in the machine interface, and the latter reveals flaws in the human interface, so to speak. For instance, you might find yourself spending a lot of text trying to explain the naming and then realize that the naming is simply bad.
socialismisok 4y ago
There are few skills more important to an engineer than concise, clear technical writing. It enables engineers to scale beyond themselves.
- simonw 4y ago
  I see strong writing skills as a vital part of leveling up to senior, staff and higher level positions. Even more important now that our world is increasingly async-first / remote-friendly.
- leghifla 4y ago
  Good writing is clearly useful and quite often mentioned. But good reading is very rarely talked about. I think it is even more important. Too many people cannot maintain attention for more than a few seconds while reading. Or they read "what they want to read" instead of the actual text. Like I write a "list of things" and they read it like "a set of things", loosing the meaningful ordering of a list. I tend to write concise documentation, but people always loose some important details that way. So I am now purposefully adding more text than strictly required to be sure important points are really understood. Like a good teacher repeats at least 3 times the same matter, with a slightly different angle
  - MaxBarraclough 4y ago
    This reminds me of an old Spolsky blog post on writing specs: [0] > Programmers often try to write specs which look like dense academic > papers. They think that a "correct" spec needs to be "technically" > correct and then they are off the hook. > > The mistake is that when you write a spec, in addition to being > correct, it has to be understandable, which, in programming terms, > means that it needs to be written so that the human brain can > "compile" it. [0] https://www.joelonsoftware.com/2000/10/15/painless-functional-specifications-part-4-tips/ https://www.joelonsoftware.com/2000/10/15/painless-functiona...
  - baby 4y ago
    I think everyone is capable of reading well-written text or code. The problem comes when it’s not well written, in which case you’re in the real of reverse engineering. And most people are bad at RE.
verdagon 4y ago
The tips at the end of the article are pretty solid. I'll add some more that helped my writing immensely: * Use bold text once or twice per section to break up the monotony and draw the reader's eye to where you want it. * Shorten! Cut away anything optional to the reader understanding your main point, and move it to footnotes, sidenotes, or a linked document/page. * Have someone read your first draft. If they ask a question, don't answer it directly! Update your draft instead. * Use lists religiously! Walls of text tend to repel attention. My favorite article [0] happened to use all these tips, if anyone wants to see an example. Happy writing! [0] https://verdagon.dev/blog/higher-raii-7drl https://verdagon.dev/blog/higher-raii-7drl
- drewcoo 4y ago
  > Use bold text Really? Why not just . . . > Shorten And as an atheist, I can't stress the next one enough. Listicles are not ideacles, or somesuchacle. Lists show a lack of pedagogical thought. > Use lists religiously!
  - Ygg2 4y ago
    > Really? Why not just . . . > > Shorten By being too terse you risk avoiding some important aspect for documentation, preventing someone from understanding it. It's a balancing act.
  - dtgriscom 4y ago
    You're being cute, but losing meaning. Do you support using lists, or do you object to them?
- jakub_g 4y ago
  About shortening: highly recommend glancing over "On Writing Well" by Zinsser. If you only have 30s, just look at this page from this book: https://scholarsandrogues.files.wordpress.com/2015/05/zinsser-book.jpeg https://scholarsandrogues.files.wordpress.com/2015/05/zinsse...
  - baby 4y ago
samsquire 4y ago
I implement algorithms from descriptions. It's so important that other developers can explain code and be capable of implementing the same thing. There's usually a critical insight that allows an algorithm to be understandable. Wikipedia descriptions for btrees, multiversion concurrency control and tries are almost enough to implement them. I don't like it when developers say the code is the documentation. I don't want to read your code to understand how you implemented the solution to the problem. I would rather read a plain explanation of what you're trying to do and what mental model you used to implement it.
TheOtherHobbes 4y ago
Whether it's FOSS or corporate, people won't use your stuff if it's not documented properly. At best they'll use it reluctantly and complain about it. One thing there isn't enough of is task-driven documentation. Typically there's a getting started guide and a reference manual, with a huge gap between the two. The getting started project is usually at the hello world level - ok as far it goes, which is not far. The ref manual typically has a list of all moving parts but often lacks a list of concepts and terminology. So you look up $thing and have no idea how it fits into what you're attempting to do. A series of mid-level task-based examples ("How do I...") for the most common use cases goes a long way to bridging that gap. Also list any platform specific quirks. (Not just "To install this use homebrew $name for MacOS and apt-get $name for Ubuntu.") And run a forum where people ask questions. Collect the most common questions into a literal FAQ and/or include them in examples/reference. Never say "That's in the manual." Especially not when the manual is 1000 pages long and gives a two sentence description of every feature with no use cases.
- ilyt 4y ago
  I do despise how little there is of examples in most of the docs. Go had a right idea of integrating example code into tests so not only there is one way to add example code, it is also guaranteed to be runnable. It also have side effect of forcing developer to use their own interface they gave to users so they might notice it is shit before people start to complain (or leave defeated and search for different lib)
  - wbeckler 4y ago
    There's a framework to do this in most major languages. I think python started this with TestDoc.
- jalino23 4y ago
  this makes sense I’m guessing this is why I love go and rust so much. it’s like I have the confidence to just figure things out when I get stuck cause of the docs it has
- rr888 4y ago
oxff 4y ago
As a software engineer, docs are quite low in priority. You should be using a language that can do documentation, like Rust, Haskell or even TS if you must use JS. If you are stuck with JavaScript you have to be careful since you might just make an API that is way more permissive than what you intended to do, or similarly if you are writing Java and need to consider what happens when concurrency happens etc.
ChrisMarshallNY 4y ago
This is something that I've always considered crucial. However, documentation is a "concrete galosh"[0], so I've learned to reduce the sheer volume of docs, and try to tie them to the code, itself. I write about my approach here[1]. [0] https://littlegreenviper.com/various/concrete-galoshes/ https://littlegreenviper.com/various/concrete-galoshes/ [1] https://littlegreenviper.com/miscellany/leaving-a-legacy/ https://littlegreenviper.com/miscellany/leaving-a-legacy/
jatins 4y ago
A thing that I started doing at previous $work was accompanying projects with an FAQ doc that'd try to answer potential product/support questions. These would be non-technical docs, that grow over time . And any time I got pinged in Slack I'd try to find the answer in that doc and link to relevant section as response. While I found that most people would not read through the entire doc when it is written or the first time it is shared for comments (can't blame them, attention spans are rare these days), they did however start referring to the the doc first after a couple of times of getting the doc link in response. Recently I read a tweet[0] that describe text as a liability, just like code. And now I feel all docs should come with an archival/revival date. We need more "canonical references" and less long living design review docs that are often shared around as reference docs. [0] https://twitter.com/thesephist/status/1592924904911163392 https://twitter.com/thesephist/status/1592924904911163392
zppln 4y ago
If you document something well people won't have to nag you over it. One of my first real job assignments was a relatively large C project (client/server architecture) behind a simple CLI. I was given the opportunity to document it relatively well (not just the CLI, but the internal design as well). Ten years later there are multiple GUI clients implemented, some even at other companies. One guy even replaced the client-server UDP protocol (don't ask) with a TCP one. Aside from reviewing pull requests for stuff like that, I don't think I've ever had to explain how any of it actually work aside from pointing them to the docs.
throwaway0asd 4y ago
Most developers I have worked with in the corporate world refuse to put things in writing. I have found the people that cannot write also cannot plan or architect software, which is then predictive of the output quality, process, and speed of delivery. It seems this is a form of executive functioning that when absent limits approaches to known patterns and oral discussions.
- analog31 4y ago
  There's a saying in the physics world, that you don't understand something unless you can explain it to a barmaid. There's also a traditional belief that you really discover the gaps in your understanding when you try to teach it. Programming languages are intended to be human readable, so it's not entirely surprising that if you can't explain something to humans, chances are you might not be explaining it very well to the computer either.
WallabyEV 4y ago
3 sentences per paragraph if long-ish, can go 5 if shorter and the rhythm is present in the cadence of language. Basically until you practice clarity, word choice, and active attention to writing (no spell check, no assists), communicating anything of complexity becomes a planning exercise. How much will it take to convey this information in text? Would a picture work better? A graph to support? I've made a nice living "translating" from Subject Matter Expert (A/C/E, SaaS, Wall St) into business language for RFPs. 9 times out of 10 a person can talk out a story to me just fine - meanwhile they've stalled writing anything for 3 days past the deadline so it's just making my life more difficult. It's obvious people hate writing in the business realm. Why? Because once it's written down there's a paper trail and accountability. That scares people who want to use language in shady ways. Hence the phone call after your email to talk about what you just mentioned but not by using the Reply button. Sooooooo predictable....
- marniewebb 4y ago
  > Why? Because once it's written down there's a paper trail and accountability. This. It’s the hard part of getting people to commit to operational plans on the business side as well.
jiriro 4y ago
What are some good tools to write and maintain documentation? I can keep docs for myslef in almost any way;) but docs maintened by a team need something easy to use. Plus on-premise storage because of security and privacy..
arminiusreturns 4y ago
Do you want your ops team waking you up at all hours of the night? Keep on giving half-assed docs to them. What should be done is gates where your shit never goes live unless you have it fully documented.
orangepurple 4y ago
My integration tests are the documentation

109 points by azhenley 4y ago

> The cartoonist Richard Guindon has a famous quote: “writing is nature’s way of letting you know how sloppy your thinking is.” You might have an impression that you understand something well, but that sense of clarity is often an illusion, and when you go to explicitly capture your understanding in a document, you discover that you didn’t understand things as well as you thought. There’s nowhere to hide in your own document. Coding is natures way of showing how sloppy your thinking is, not writing natural language text. It is really easy to hide sloppy thinking behind natural language, otherwise there would be a lot of overlap between great writers and great coders, but there doesn't seem to be much correlation there at all. Coders tend to be precise with their language, but most people prefer to read imprecise sentences so you easily gravitate towards imprecise language if you try to practice writing.

mrich 4y ago
And testing is nature's way of telling you how sloppy your code is, I suppose? (recursion intended)
- Jensson 4y ago
  Yeah, testing shows you that your code is sloppy, writing is even worse since there is no testing at all, even the worst code is better tested than the best text as long as the programmer ran it once.
  - KronisLV 4y ago
    > writing is even worse since there is no testing at all Isn't it possible to get a beta reader? Just someone who will go through your writing and give you feedback? If you are writing docs, a lot of the time you'll also have coworkers there with you, that you'll be able to float the docs to for a quick look, or maybe other people who are interested in your project, if doing open source, or even a friend. It is a bit worse than automated testing, but surely better than nothing! Also, there are apps or sites like this, that help you detect when you have run on sentences or complicated wording: https://hemingwayapp.com/ https://hemingwayapp.com/ Those could sometimes be useful.
gandalfgreybeer 4y ago
> Coders tend to be precise with their language, but most people prefer to read imprecise sentences so you easily gravitate towards imprecise language if you try to practice writing. Preferring to read imprecise sentences comes down to what the purpose of the written work is, does it not? Clear and precise technical documentation and even research papers are really helpful and can be practiced. If it’s poetry or a level of emotional buildup such as in fiction is needed, then that’s what people will prefer. Context on what is being written matters.
- Jensson 4y ago
  In theory yes, in practice documentation tends to be too sloppy to be useful. The problem is that writing all the details is equivalent to just providing the source code, so you need to explain less. But then unless what you are working with has very clean abstractions the documentation becomes worthless because it doesn't explain things well enough. So in practice documentation for a codebase is mostly worthless unless the codebase is very cleanly written, which wont be the case unless we are talking about programming languages or similar. The real documentation people use in codebases is looking at how things are used in other parts of the codebase. Then you have examples and maybe even tests showing how it works, so you start from there and maybe test some things if you need to do things a bit differently. So when is documentation actually useful? When you provide a library that is intended to be used outside of your codebase, so a person who adds the library to his codebase can understand how to use it without having examples to look at in their code. But this is a very specific case and most software engineers don't have to think about it. If I'm missing something here please explain why, but I've never found any documentation to be useful, except for libraries from outside your codebase. And even for libraries it is often easier and faster to just read the source code if it is available. Edit: If you are talking about design documents for services and features then those are useful, yes, but that is usually not what people talk about when they talk about software engineers writing documentation.
  - knighthack 4y ago
    > If I'm missing something here please explain why, but I've never found any documentation to be useful, except for libraries from outside your codebase. And even for libraries it is often easier and faster to just read the source code if it is available. For simple packages, I understand. For anything else, you are committing hyperbolic falsehood if you (or others) claim that it is "easier and faster to just read the source code" and "even for libraries", compared to reading examples/well-written documentation.
cratermoon 4y ago
“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” – Martin Fowler
olau 4y ago
I've personally found that to write a good API, you need both code that implements the API and code that uses it, and you also need to write the documentation of that API. The former reveals flaws in the machine interface, and the latter reveals flaws in the human interface, so to speak. For instance, you might find yourself spending a lot of text trying to explain the naming and then realize that the naming is simply bad.

socialismisok 4y ago

There are few skills more important to an engineer than concise, clear technical writing. It enables engineers to scale beyond themselves.

simonw 4y ago
I see strong writing skills as a vital part of leveling up to senior, staff and higher level positions. Even more important now that our world is increasingly async-first / remote-friendly.
leghifla 4y ago
Good writing is clearly useful and quite often mentioned. But good reading is very rarely talked about. I think it is even more important. Too many people cannot maintain attention for more than a few seconds while reading. Or they read "what they want to read" instead of the actual text. Like I write a "list of things" and they read it like "a set of things", loosing the meaningful ordering of a list. I tend to write concise documentation, but people always loose some important details that way. So I am now purposefully adding more text than strictly required to be sure important points are really understood. Like a good teacher repeats at least 3 times the same matter, with a slightly different angle
- MaxBarraclough 4y ago
  This reminds me of an old Spolsky blog post on writing specs: [0] > Programmers often try to write specs which look like dense academic > papers. They think that a "correct" spec needs to be "technically" > correct and then they are off the hook. > > The mistake is that when you write a spec, in addition to being > correct, it has to be understandable, which, in programming terms, > means that it needs to be written so that the human brain can > "compile" it. [0] https://www.joelonsoftware.com/2000/10/15/painless-functional-specifications-part-4-tips/ https://www.joelonsoftware.com/2000/10/15/painless-functiona...
- baby 4y ago
  I think everyone is capable of reading well-written text or code. The problem comes when it’s not well written, in which case you’re in the real of reverse engineering. And most people are bad at RE.

verdagon 4y ago

The tips at the end of the article are pretty solid. I'll add some more that helped my writing immensely: * Use bold text once or twice per section to break up the monotony and draw the reader's eye to where you want it. * Shorten! Cut away anything optional to the reader understanding your main point, and move it to footnotes, sidenotes, or a linked document/page. * Have someone read your first draft. If they ask a question, don't answer it directly! Update your draft instead. * Use lists religiously! Walls of text tend to repel attention. My favorite article [0] happened to use all these tips, if anyone wants to see an example. Happy writing! [0] https://verdagon.dev/blog/higher-raii-7drl https://verdagon.dev/blog/higher-raii-7drl

drewcoo 4y ago
> Use bold text Really? Why not just . . . > Shorten And as an atheist, I can't stress the next one enough. Listicles are not ideacles, or somesuchacle. Lists show a lack of pedagogical thought. > Use lists religiously!
- Ygg2 4y ago
  > Really? Why not just . . . > > Shorten By being too terse you risk avoiding some important aspect for documentation, preventing someone from understanding it. It's a balancing act.
- dtgriscom 4y ago
  You're being cute, but losing meaning. Do you support using lists, or do you object to them?
jakub_g 4y ago
About shortening: highly recommend glancing over "On Writing Well" by Zinsser. If you only have 30s, just look at this page from this book: https://scholarsandrogues.files.wordpress.com/2015/05/zinsser-book.jpeg https://scholarsandrogues.files.wordpress.com/2015/05/zinsse...
- baby 4y ago

samsquire 4y ago

I implement algorithms from descriptions. It's so important that other developers can explain code and be capable of implementing the same thing. There's usually a critical insight that allows an algorithm to be understandable. Wikipedia descriptions for btrees, multiversion concurrency control and tries are almost enough to implement them. I don't like it when developers say the code is the documentation. I don't want to read your code to understand how you implemented the solution to the problem. I would rather read a plain explanation of what you're trying to do and what mental model you used to implement it.

TheOtherHobbes 4y ago

Whether it's FOSS or corporate, people won't use your stuff if it's not documented properly. At best they'll use it reluctantly and complain about it. One thing there isn't enough of is task-driven documentation. Typically there's a getting started guide and a reference manual, with a huge gap between the two. The getting started project is usually at the hello world level - ok as far it goes, which is not far. The ref manual typically has a list of all moving parts but often lacks a list of concepts and terminology. So you look up $thing and have no idea how it fits into what you're attempting to do. A series of mid-level task-based examples ("How do I...") for the most common use cases goes a long way to bridging that gap. Also list any platform specific quirks. (Not just "To install this use homebrew $name for MacOS and apt-get $name for Ubuntu.") And run a forum where people ask questions. Collect the most common questions into a literal FAQ and/or include them in examples/reference. Never say "That's in the manual." Especially not when the manual is 1000 pages long and gives a two sentence description of every feature with no use cases.

ilyt 4y ago
I do despise how little there is of examples in most of the docs. Go had a right idea of integrating example code into tests so not only there is one way to add example code, it is also guaranteed to be runnable. It also have side effect of forcing developer to use their own interface they gave to users so they might notice it is shit before people start to complain (or leave defeated and search for different lib)
- wbeckler 4y ago
  There's a framework to do this in most major languages. I think python started this with TestDoc.
jalino23 4y ago
this makes sense I’m guessing this is why I love go and rust so much. it’s like I have the confidence to just figure things out when I get stuck cause of the docs it has
rr888 4y ago

oxff 4y ago

As a software engineer, docs are quite low in priority. You should be using a language that can do documentation, like Rust, Haskell or even TS if you must use JS. If you are stuck with JavaScript you have to be careful since you might just make an API that is way more permissive than what you intended to do, or similarly if you are writing Java and need to consider what happens when concurrency happens etc.

ChrisMarshallNY 4y ago

This is something that I've always considered crucial. However, documentation is a "concrete galosh"[0], so I've learned to reduce the sheer volume of docs, and try to tie them to the code, itself. I write about my approach here[1]. [0] https://littlegreenviper.com/various/concrete-galoshes/ https://littlegreenviper.com/various/concrete-galoshes/ [1] https://littlegreenviper.com/miscellany/leaving-a-legacy/ https://littlegreenviper.com/miscellany/leaving-a-legacy/

jatins 4y ago

A thing that I started doing at previous $work was accompanying projects with an FAQ doc that'd try to answer potential product/support questions. These would be non-technical docs, that grow over time . And any time I got pinged in Slack I'd try to find the answer in that doc and link to relevant section as response. While I found that most people would not read through the entire doc when it is written or the first time it is shared for comments (can't blame them, attention spans are rare these days), they did however start referring to the the doc first after a couple of times of getting the doc link in response. Recently I read a tweet[0] that describe text as a liability, just like code. And now I feel all docs should come with an archival/revival date. We need more "canonical references" and less long living design review docs that are often shared around as reference docs. [0] https://twitter.com/thesephist/status/1592924904911163392 https://twitter.com/thesephist/status/1592924904911163392

zppln 4y ago

If you document something well people won't have to nag you over it. One of my first real job assignments was a relatively large C project (client/server architecture) behind a simple CLI. I was given the opportunity to document it relatively well (not just the CLI, but the internal design as well). Ten years later there are multiple GUI clients implemented, some even at other companies. One guy even replaced the client-server UDP protocol (don't ask) with a TCP one. Aside from reviewing pull requests for stuff like that, I don't think I've ever had to explain how any of it actually work aside from pointing them to the docs.

throwaway0asd 4y ago

Most developers I have worked with in the corporate world refuse to put things in writing. I have found the people that cannot write also cannot plan or architect software, which is then predictive of the output quality, process, and speed of delivery. It seems this is a form of executive functioning that when absent limits approaches to known patterns and oral discussions.

analog31 4y ago
There's a saying in the physics world, that you don't understand something unless you can explain it to a barmaid. There's also a traditional belief that you really discover the gaps in your understanding when you try to teach it. Programming languages are intended to be human readable, so it's not entirely surprising that if you can't explain something to humans, chances are you might not be explaining it very well to the computer either.

WallabyEV 4y ago

3 sentences per paragraph if long-ish, can go 5 if shorter and the rhythm is present in the cadence of language. Basically until you practice clarity, word choice, and active attention to writing (no spell check, no assists), communicating anything of complexity becomes a planning exercise. How much will it take to convey this information in text? Would a picture work better? A graph to support? I've made a nice living "translating" from Subject Matter Expert (A/C/E, SaaS, Wall St) into business language for RFPs. 9 times out of 10 a person can talk out a story to me just fine - meanwhile they've stalled writing anything for 3 days past the deadline so it's just making my life more difficult. It's obvious people hate writing in the business realm. Why? Because once it's written down there's a paper trail and accountability. That scares people who want to use language in shady ways. Hence the phone call after your email to talk about what you just mentioned but not by using the Reply button. Sooooooo predictable....

marniewebb 4y ago
> Why? Because once it's written down there's a paper trail and accountability. This. It’s the hard part of getting people to commit to operational plans on the business side as well.

jiriro 4y ago

What are some good tools to write and maintain documentation? I can keep docs for myslef in almost any way;) but docs maintened by a team need something easy to use. Plus on-premise storage because of security and privacy..

arminiusreturns 4y ago

Do you want your ops team waking you up at all hours of the night? Keep on giving half-assed docs to them. What should be done is gates where your shit never goes live unless you have it fully documented.

orangepurple 4y ago

My integration tests are the documentation