4 ms·

I can't stress this enough. Know your audience and tailor your documentation to them. You should write three types of documentation. One for users, one for ad

I can't stress this enough. Know your audience and tailor your documentation to them. You should write three types of documentation. One for users, one for admins and one about architecture. User docs are simple. How do I use it. What are the API calls, etc. Admin docs are about how to install/break-fix/troubleshoot issues that are beyond user interaction. Architecture is how the system is constructed, why certain tech was chosen, etc. There's nothing that makes documentation more useless than when you're trying to do something like install the software but you have to dig thru piles of docs about why Postgres was chosen over MySQL. If your users or admins cant find the info they need quickly, they'll soon discard the documentation and user/system ops will go back to word of mouth knowledgeable. I really think good companies focus on this and those who are successful really shine.

Cthulhu_ 3y ago
There's another category that's missing from most of the (enterprisey) companies I've worked at; procedures. Think of the result of an event storming session; consider all the steps involved in all layers of your application when a user creates a new session, or wants to do X in your application. Ex: I work in the energy sector at the moment; because their gas/electricity usage varies across the year, there's a system in place where they pay a fixed amount per month, then they pay or get paid back the difference by the end of a contract year. It's in the energy company's best interest that the monthly amount they pay is on par. The process to adjust this monthly amount is administrative, but in addition to that there's a huge stack of things to deal with across platforms; website, apps, back-end, support, support user interface, etc etc etc. All the processes involved in just this aspect of the company need to be documented and drawn out as well, because else it has to be figured out from code or various people that happen to have it in their head. That's where a lot of the meeting culture comes from, because there's no one person in charge of this process, and the ones that know enough don't get together to write it down (and then maintain that documentation).
- syntheweave 3y ago
  I hit an oddly specific realization this weekend while working on an architectural spec: I make better documentation with a color multipen. The reason why is because it allows a diagram to support more of the cross-cutting concerns by drawing a red arrow or a green arrow through things instead of a blue one. It's a big moment in my realizations around technical communication. Like, I already knew this stuff mattered, but it's made more concrete when you can look at a diagram and the holistic whole helps you make more sense of things even if the details aren't right yet.
alexpotato 3y ago
> You should write three types of documentation. One for users, one for admins and one about architecture. I use an airplane analogy (different order than your three above): 1. "Congratulations on purchasing your 747" 2. "This is how you replace the auxiliary power unit" 3. "This is how you survive the engine catching fire"
- remram 3y ago
  1 is not documenting anything, and both 1 and 3 are meant for pilots? Who are the "users" in this analogy?
  - nwatson 3y ago
    "1" is for the airline. What does purchasing the plane, or a fleet of such planes, mean to the company? What will be the benefits, duties, obligations wrt to the airplanes, at a high level? Edit: word choice
  - JdeBP 3y ago
    On the contrary, 1 would be a "quickstart guide", a "welcome pack", or even just a "The first thing that you need to do to your new washing machine/jet aircraft is take the restraining bolts, used for immobilizing it during transport, off."
makeitdouble 3y ago
It could help to use more specific terminology than "docs". If I'm properly getting your point, you think there should be user manuals, administration and maintenance procedures, and architecture specifications and/or decision records.
crispyambulance 3y ago
I agree with everything you said, especially tailoring documentation for intended purpose. Except... > User docs are simple. User docs are NOT simple. You have to put yourself into the mind of someone who is going to use your software to solve a problem which they have. That's never easy and it gets really hard, really fast, as the software grows in complexity or as your audience gets wider.
- muser8 3y ago
  To continue this line of thinking: for documents to be useful in helping a customer solve a problem the documents must answer the question 'why would I want to do X.' A complete reference of how to do A, ..., X, Y, and Z but lacking conceptual context could actually be detrimental to a customer's productivity and the ultimate success of your product. Providing accessible conceptual guidance can be very challenging depending on the domain.
- SkipperCat 3y ago
  I should probably elaborate. When saying simple, I meant don't add content that doesn't relate to what the user needs to use the product. There's nothing worse than having to read a several paragraphs of unrelated content just to get to the nugget of info which tells you how to actually use the product. If the user needs complex docs to perform a complex task - that's 100% OK. Just don't write complex content when a simple (or direct) explanation will do.
mwilliamson 3y ago
Reminds me of the four types of documentation that sometimes get listed: tutorials, how-to guides, technical reference and explanation. (Usual caveat of all models are wrong but some are useful.) https://documentation.divio.com/ https://documentation.divio.com/ My (perhaps overly simplistic) take would be that we should take the thinking we use on the product itself (Who's going to use it? In what context? What would they already know? And so on), and apply and adapt it to the docs as we would any other product.
- dotandgtfo 3y ago
  I strongly back the Divio system for documentation, it works great. But you should know that the creator of the system doesn't work at Divio anymore and the newest iteration is now called Diataxis https://diataxis.fr/ https://diataxis.fr/
- ren_engineer 3y ago
  the divio style docs concept got further refined by the creator with this - https://diataxis.fr/ https://diataxis.fr/ mostly the same but some additional information for people who are interested
deleted 3y ago
[deleted]
MilStdJunkie 3y ago
Surfing close to Robert Horn's Information Mapping. Which is a useful construct, but it's a dangerous idea to think that content information types just sort of live . . out there, somewhere. Content typing will always be context - dependent, which, well, can boil down to "know your audience". But the content types aren't General Truth, they do need audience to be defined, which is where I disagree with the DITA folks.
NiklasBegley 3y ago
Agreed on a lot of this, but I'd be cautious about saying that any kind of documentation is "simple". Especially when it comes to technical products - be they internal or external. Technical writers train specifically to communicate complex technical topics to readers, and it's not an easy job. It requires understanding your readers, what kind of backgrounds they have, and what are they trying to achieve. This becomes especially important for documentation that is meant for your customers, where very real revenue depends on the quality of your docs. I'm a bit biased since I'm the founder of a documentation startup [0], but tools also do play a big part. Devs often tend to enjoy writing something Markdown next to their code than going to an old wiki like Confluence that's disconnected from the engineering cycle. Choosing the right tool lowers the barrier to keeping the docs up to date. [0]: https://www.doctave.com https://www.doctave.com
- jrumbut 3y ago
  > disconnected from the engineering cycle Great phrase! To me, there are three places that dev-generated documentation can live: 1. The code 2. The issue tracker 3. The version control system A small amount of exceptionally useful and frequently referred to documentation like the process for setting up a new dev environment or some complex support task can live elsewhere. Otherwise, I think the top down imposition of a documentation culture is unlikely to succeed. The real secret to getting a team that has a shared understanding of the system, the business, and each other is to retain your developers. A team that's been together for five years has superpowers no amount of documentation can replicate.

Cthulhu_ 3y ago

There's another category that's missing from most of the (enterprisey) companies I've worked at; procedures. Think of the result of an event storming session; consider all the steps involved in all layers of your application when a user creates a new session, or wants to do X in your application. Ex: I work in the energy sector at the moment; because their gas/electricity usage varies across the year, there's a system in place where they pay a fixed amount per month, then they pay or get paid back the difference by the end of a contract year. It's in the energy company's best interest that the monthly amount they pay is on par. The process to adjust this monthly amount is administrative, but in addition to that there's a huge stack of things to deal with across platforms; website, apps, back-end, support, support user interface, etc etc etc. All the processes involved in just this aspect of the company need to be documented and drawn out as well, because else it has to be figured out from code or various people that happen to have it in their head. That's where a lot of the meeting culture comes from, because there's no one person in charge of this process, and the ones that know enough don't get together to write it down (and then maintain that documentation).

syntheweave 3y ago
I hit an oddly specific realization this weekend while working on an architectural spec: I make better documentation with a color multipen. The reason why is because it allows a diagram to support more of the cross-cutting concerns by drawing a red arrow or a green arrow through things instead of a blue one. It's a big moment in my realizations around technical communication. Like, I already knew this stuff mattered, but it's made more concrete when you can look at a diagram and the holistic whole helps you make more sense of things even if the details aren't right yet.

alexpotato 3y ago

> You should write three types of documentation. One for users, one for admins and one about architecture. I use an airplane analogy (different order than your three above): 1. "Congratulations on purchasing your 747" 2. "This is how you replace the auxiliary power unit" 3. "This is how you survive the engine catching fire"

remram 3y ago
1 is not documenting anything, and both 1 and 3 are meant for pilots? Who are the "users" in this analogy?
- nwatson 3y ago
  "1" is for the airline. What does purchasing the plane, or a fleet of such planes, mean to the company? What will be the benefits, duties, obligations wrt to the airplanes, at a high level? Edit: word choice
- JdeBP 3y ago
  On the contrary, 1 would be a "quickstart guide", a "welcome pack", or even just a "The first thing that you need to do to your new washing machine/jet aircraft is take the restraining bolts, used for immobilizing it during transport, off."

makeitdouble 3y ago

It could help to use more specific terminology than "docs". If I'm properly getting your point, you think there should be user manuals, administration and maintenance procedures, and architecture specifications and/or decision records.

crispyambulance 3y ago

I agree with everything you said, especially tailoring documentation for intended purpose. Except... > User docs are simple. User docs are NOT simple. You have to put yourself into the mind of someone who is going to use your software to solve a problem which they have. That's never easy and it gets really hard, really fast, as the software grows in complexity or as your audience gets wider.

muser8 3y ago
To continue this line of thinking: for documents to be useful in helping a customer solve a problem the documents must answer the question 'why would I want to do X.' A complete reference of how to do A, ..., X, Y, and Z but lacking conceptual context could actually be detrimental to a customer's productivity and the ultimate success of your product. Providing accessible conceptual guidance can be very challenging depending on the domain.
SkipperCat 3y ago
I should probably elaborate. When saying simple, I meant don't add content that doesn't relate to what the user needs to use the product. There's nothing worse than having to read a several paragraphs of unrelated content just to get to the nugget of info which tells you how to actually use the product. If the user needs complex docs to perform a complex task - that's 100% OK. Just don't write complex content when a simple (or direct) explanation will do.

mwilliamson 3y ago

Reminds me of the four types of documentation that sometimes get listed: tutorials, how-to guides, technical reference and explanation. (Usual caveat of all models are wrong but some are useful.) https://documentation.divio.com/ https://documentation.divio.com/ My (perhaps overly simplistic) take would be that we should take the thinking we use on the product itself (Who's going to use it? In what context? What would they already know? And so on), and apply and adapt it to the docs as we would any other product.

dotandgtfo 3y ago
I strongly back the Divio system for documentation, it works great. But you should know that the creator of the system doesn't work at Divio anymore and the newest iteration is now called Diataxis https://diataxis.fr/ https://diataxis.fr/
ren_engineer 3y ago
the divio style docs concept got further refined by the creator with this - https://diataxis.fr/ https://diataxis.fr/ mostly the same but some additional information for people who are interested

deleted 3y ago

[deleted]

MilStdJunkie 3y ago

Surfing close to Robert Horn's Information Mapping. Which is a useful construct, but it's a dangerous idea to think that content information types just sort of live . . out there, somewhere. Content typing will always be context - dependent, which, well, can boil down to "know your audience". But the content types aren't General Truth, they do need audience to be defined, which is where I disagree with the DITA folks.

NiklasBegley 3y ago

Agreed on a lot of this, but I'd be cautious about saying that any kind of documentation is "simple". Especially when it comes to technical products - be they internal or external. Technical writers train specifically to communicate complex technical topics to readers, and it's not an easy job. It requires understanding your readers, what kind of backgrounds they have, and what are they trying to achieve. This becomes especially important for documentation that is meant for your customers, where very real revenue depends on the quality of your docs. I'm a bit biased since I'm the founder of a documentation startup [0], but tools also do play a big part. Devs often tend to enjoy writing something Markdown next to their code than going to an old wiki like Confluence that's disconnected from the engineering cycle. Choosing the right tool lowers the barrier to keeping the docs up to date. [0]: https://www.doctave.com https://www.doctave.com

jrumbut 3y ago
> disconnected from the engineering cycle Great phrase! To me, there are three places that dev-generated documentation can live: 1. The code 2. The issue tracker 3. The version control system A small amount of exceptionally useful and frequently referred to documentation like the process for setting up a new dev environment or some complex support task can live elsewhere. Otherwise, I think the top down imposition of a documentation culture is unlikely to succeed. The real secret to getting a team that has a shared understanding of the system, the business, and each other is to retain your developers. A team that's been together for five years has superpowers no amount of documentation can replicate.