I write about German bureaucracy, and I wholeheartedly agree with your approach.
Most of my guides start with: what this is, who needs to do this, why you need to do this. If you don’t confirm that people are on the right page doing the right thing for the right reasons, they can go really far in the wrong direction.
Most government websites don’t explain any of this. They just tell you what they want from you to complete the part of the task that concerns them. They don’t bother to treat the task as part of a bigger decision. They just assume that you are here because you know what you are doing.
Re your last paragraph, the UK gov website excels at this. There are landing pages which describe the process, then warnings and caveats, then you can actually fill in the forms.
> If you don’t confirm that people are on the right page doing the right thing for the right reasons
Based on this comment I think you would appreciate Every Page Is Page One a lot. The basic idea is that people can and will land on any random page of your docs site, so every page needs to quickly ground them and make it super easy for them decide whether they're on the right path or no. That's where the book title is coming from. Literally any page of your site might be page one for a user.
That’s exactly how I design my content! I work really hard on making sure that every entry point leads to the right path. It’s surprisingly challenging.
Thank you for the book recommendation. I will give it a look.
This is a really good approach I wish more technical docs had. My mind is always questioning why things are done a certain way, which leads me to side quests that slow me down.
This fits the way I like to use LLMs: I always ask them for options, then I decide myself which of those options makes the most sense.
Essentially I'm using them as weird magical documentation that can spit out (incomplete but still useful) available options to guide my decision making at any turn.
I like to think of it as the apprentices working for famous artists like Leonardo. The master would draw the outline/sketch, and then the students would fill in the blanks under supervision. Sometimes, the master would steal ideas from the students.
Smells like reinforcement learning in real life. Master sets ups the task environment, collects samples from students, picks the best and maybe even augments them. Students watch the master and learn... and the cycle continues.
And then the master becomes a grandmaster (unless entropy explosion occurs).
Yea, and it's what ChatGPT does sometimes even if you don't ask it for multiple options. It shows two options and asks you to select the best one. Essentially using customers to help with training.
Not exactly the same… But recently I wanted to pick a library in Python or Julia for simulating differential equations using a GPU. So I asked ChatGPT which libraries exist for this (JAX, CuPy, etc.), asked it to generate code to solve e.g. the 2D heat equation on a 1000x1000 grid for 100 time steps using each of those frameworks. Then I stepped in and verified that each code appeared to do the same thing, and proceeded to benchmark their performance on my hardware. Afterwards I had an informed choice of which framework to use for my project, even though ChatGPT gave me the benchmark code instead of the answer.
Similarly I find Bing copilot very handy for exploring problem spaces and their solution spaces. Then i dig/ask deeper and deeper until i understand the solution. It is a quick way to brainstorm without diverting too much, and hence converging, since that tech knows a lot details about a lot of things.
Here's one: if you want it to rewrite something or show you a better way to say something you've already written, just ask for different options. I usually find that mixing what I wanted to write with parts of its suggestions gives me a great result.
I love this. Short, to the point, and insightful. I’m one of those ‘big picture’ type of thinkers. It’s really important to me to just not know the how behind something, but also the why and how it relates to the larger context. I encourage our developers to make liberal use of the Description field in Jira stories and tasks and provide an overview of why we are doing something and how it relates to the bigger picture. Some of them don’t like it I guess, but some are really digging it. I’m happy to provide the big picture behind the project and they are happy with added independence understanding the big picture gives them.
It seems like it's a lot harder to measure whether your docs are helping people make good decisions than it is to measure whether they are helping people successfully accomplish a task. I think we optimize for task-based/procedural docs because the business needs us to prove our value, and there is a need for this type of documentation, and there are lots of ways to measure and report on it over short timelines. But answering the question of, "Did this docset help someone build the right thing in the right way", I mean...organizations struggle to answer this question about their own products, abstracting that to try and measure the effectiveness of your docs seems super fuzzy.
Which is not to say you can't write docs that do this, just that it seems very hard to use numbers to prove that you have done so. I definitely think I could rank how well different docsets support users who need to make decisions, and I could offer up explanations to support my reasoning, but I don't know how to quantify that for the business.
I wonder how the structure of a docset that is designed to support decisions differs from that of a docset that supports tasks. I expect you'll have the same main categories (conceptual, reference, guides) but maybe a lot more conceptual docs, and more space dedicated to contextualizing the concepts. I would expect to see topics become more interdependent, more cross-references, etc.
Interesting that your first thought here is not, oh, how can I use this to improve the docs I am writing, but it is, how can I prove that this improves the docs I am writing. You seem to live in a though environment.
You're getting a taste of the world that a lot of professional technical writers live in. Everyone seems to intuitively understand that you need docs, and that if you don't invest in docs it probably will be bad for the business, yet at the same time it's hard to concretely show business value. So technical writers are incessantly asked to prove their value, even though the managers subconsciously know that they're important for some reason. Over the years I have come to believe that docs are important simply because it's a primary mechanism for sharing knowledge across the company and to customers. Michelle Irvine has been doing great work quantifying this: https://cloud.google.com/blog/products/devops-sre/deep-dive-...
You're not wrong. Business is a tough environment.
At a gut level the post seems sensible to me, and it does generate a lot of ideas about how I can make my own docs better. That's not enough, though, if I want the folks who think about docs at my org to change their approach.
As the OP states in several other comments, most writers and organizations learn to prioritize task-based documentation. If we want to adopt a better way of doing things, we need to be able to communicate why it's better. It's no different in other disciplines.
Exactly. Or you become an island doing the good but sometimes barely scratching the surface of what could be possible (to the detriment of your users).
Another aspect of this is that it may take you more time to complete your assignments and you get labeled as slow.
In my own personal projects, where I'm free to do whatever I think is best for my users, I will probably adopt "support decisions" as the foundation of my docs strategy.
In the spirit of working with integrity, if I feel that "support decisions" is the best approach for my own projects, then I probably have a duty to bring this strategy into the docs I do for work.
Luckily I don't have short-sighted managers breathing down my neck, but if I had to convince people at work I would go about it like this:
* Explain the logic of the strategy. Supporting decisions just seems to make sense and ring true . The tasks will still get documented, but tasks are just a subset of decision support.
* And then I would provide a long list of examples from support tickets, chat room discussions, etc. where lack of decision support seemed to be the problem. For intellectual honesty I would show the complete list of docs-related support tickets (for example) and then the subset that were related to supporting decisions. If it's a non-trivial percent (maybe 25%) then we should really look into "decision support" more.
* Last, I might provide examples that the stakeholders themselves have faced in their own work. "Remember how difficult it was to decide what CMS to switch to??"
Thinking in Bets has been one of the most useful books to how I approach software engineering. It’s not even about code, just how to make decisions effectively in limited information environments.
Love that book. Such a powerful idea to phrase your predictions in terms of percentages rather than absolutes. Apparently the Super Bowl anecdote is controversial though? I.e. the conclusions to draw from that anecdote are very debatable.
Well “fuzzy logic” is kind of a dated term. I don’t think it has been used in software development, for twenty years.
TL;DR, It basically means not having “hard and fast” boundaries, and instead, having ranges of target values, and “rules” for determining target states, as opposed to “milestones,” so targets are determined on a “one at a time” basis.
When we think of future, mostly we think in a deterministic one single point in the future. I would like to think of future as "possible states" rather than just a single point.
This helps me prepare for different scenarios and then build on top of whatever opportunity comes along.
I got reminded of it when I read "target states" and so thought will share it.
> "The key to strategy, little Vor," she explained kindly, "is not to choose a path to victory, but to choose so that all paths lead to a victory." —LMB
The term the ancients had for this was paying attention to the "weakest precondition".
When you are playing against an opponent, yes, you need a min-max strategy.
But then you are not, optimizations are exactly what that name sounds. You usually need to max some goal while you min some weakly correlated one, what sounds similar, but you can pick exactly what "preconditions" you will optimize against. You don't need to cover them all.
"Weakest precondition" is a term of art, specifically referring to predicate transformer semantics[0].
I think we must be interpreting that phrase differently?
Otherwise[1] I'd claim the opposite: when playing against an opponent, one ought merely retain an advantage, which is a weaker predicate than even the weakest liberal precondition, but when playing against entropy (the sheer bloody-mindedness, or at least sufficiently advanced ineptitude, of one's users; or the yolo-tude of whatever provided their data; etc.), especially at several GHz on multiple cores, one should ensure the strict WP.
[1] unless you're one of those (hopefully rare) devs who always produce fault-tolerant systems — under the principle that ultimately users can be relied upon to tolerate the faults.
Ok. I don't think we are talking about different things, and I still think you got it the other way around.
In fuzzy terms (because boolean logic gets crazy with those concepts):
We have success "S", with preconditions "P0, P1, ...", so that S = P0 & P1 & ...
We can map those concepts into their probability, where the probability of success would be "s = p0 * p1 * ...". AFAIK, your rule is that the best place to optimize is the lowest pN.
That would only be true if optimizing for any of those preconditions had similar costs and values. But on business, those things both tend to vary wildly, and the entire thing tends to get dominated by preconditions that you can't control (infinite costs) very quickly once you achieve a minimum of competence.
Also, the formalism doesn't accept changes on the definition of "success". You will get absolutely nowhere in life if you don't constantly change your definition of success, so the formalism is irredeemably wrong by construction.
I've advocated something similar. Don't just describe the tool at a high level (people often seem to go into marketing mode) - tell the story of what problem it was designed to solve and the trade offs you made along the way. Makes it much easier to place the tool and available options/modes/etc in context and quickly decide whether it's a good fit for you.
I am a bit confused about this advice. Who's decisions? The tool makers? Or the users?
In general, this seems like an oversimplification. It's more useful to first understand what kind of document you are writing: learning, goal-oriented, understanding, or information. [1] It would be annoying to look up the API for a function and get inundated with "decision" information, for example.
The docs should always be addressing a user need. That does not go away. Neither does Diataxis (the four quadrants of docs that you mentioned). I think this post is striking a chord because it's unsurfacing a blind spot in the two well-known strategies you mentioned. Everyone tries to make user-focused docs and many follow Diataxis, yet we still struggle to get stuff done with docs. Starting from the foundational viewpoint of the "docs should support decisions" might be a way to make docs more useful.
Knowing how people use your system to make decisions is important. I think that knowledge is vital for maintaining, extending, or building a system.
But the article suggests a higher responsibility: you should document your user's decision-making. You should tell them the context, the choices they have to make, and the consequences of their decisions.
I've worked on a "decision support system" with that responsibility and it got really messy, really fast. Humans love to argue about consequences, even 100% absolutely known ones. They also despise automated emails bearing uncertainty, as well as docs demanding binary choices when many more choices are available in reality.
I would hope the book beyond this article raises the concept of control. That is, to document a behavior, you need some guarantee (or enforcement) about that behavior so your documentation remains authoritative. IMO, the lack of authority/control is common, gaping blindspot of writing initiatives like https://www.plainlanguage.gov unfortunately.
Quoting myself from r/technicalwriting discussion on this post:
> Let me rephrase what I think is really important about Baker's idea. The dogma of technical writing education absolutely revolves around focusing on tasks. If we survey a lot of professional technical writers I will bet you that a majority of them believe that "helping users achieve tasks" is a primary goal of documentation, if not THE primary goal. This small quote from Baker is kinda radical (in the Latin sense of "going to the roots"), because it's suggesting that one of our fundamental assumptions is majorly lacking.
For me personally, Baker's idea is fascinating simply because it sets the bar a lot higher than the current status quo of what's expected of technical writing. A lot of docs just assume that it's "mission complete" once a task is documented, and Baker (to me) is suggesting that it's simply not enough. Tasks of course still need to be documented, but tasks are a subset of the information that goes into decisions.
I don't recall Baker's book discussing control in the way you mention. It's a new idea to me, thanks for sharing. One concrete example of control that comes to mind: if a lot of my docs rely on a page from another open source project, and that external page is not good (low quality), then it should probably be my responsibility to improve that doc. Many people might assume that docs external to their site are outside of their responsibility. But if you're really committed to supporting decisions then it doesn't really matter who is hosting the doc. Maybe there's a lot to learn from the ethos of being a good open source citizen in general
Over on r/technicalwriting I'm having a debate with someone regarding whether this is a general principle or not. To be clear, I have no idea how niche or widespread this problem, is. My hunch is that it's a brilliant insight that applies to technical writing in many industries. For now it's just an idea that I think deserves a lot more thought and discussion.
I’d say it’s an interesting phrasing of a general principle, namely the four types of technical documentation. “Preparing people for decisions” is the first and third types (references and explanations) and “guiding people through tasks” is the second and fourth types (instructions and tutorials). IMO!
They say you should not judge a book by its cover, but I found it very hard not to [1]. After I found out the book was from 2013 I felt a slight sense of relief.
It's surely related to the central thesis of the book (quoted below) but I think there could have been a more appealing way to get that idea across
> What is needed today is the same rigor and discipline professional writers have long brought to making books, but not the same methodology. The book model does not work for the Web or for content consumed in the context of the Web.
This is very much not part of the canon of technical writing dogma, so yes it is profound to me. Professional technical writers are trained from day one to assume that the job revolves around task completion.
THIS GENIUS ALBERTO LITERALLY SAVED ME WHEN HE HELPED ME HACKK INTO 2 PHONES WHICH HARD SOME OF MY PICTURES AND I WAS BEING BLACKMAILED. THIS MAN HELPED ME GAIN ACCESS TO BOTH PHONES WITHIN 5 HOURS. I DELETED THE PICTURES MYSELF FROM MY COMPUTER. I ALSO HAD ACCESS TO ALL THE MESSAGES, PICTURES AND VIDEOS ON THIER PHONES. IF YOU NEED HELP, MESSAGE ALBERTO VIA EMAILL:
VADIMWEBHACK@ GMAILL,C0M (HE IS ALSO AVAILABLE ON WHATSAPP AND TELEGRAM)
THIS MAN ALSO HELPED A FRIEND OF MINE RECOVER BITCOINS SHE LOST FAKE INVESTMENT SCHEME ONLINE. HE OFFERS A LOT OTHER SERVICES I CAN'T TALK ABOUT HERE.
I write about German bureaucracy, and I wholeheartedly agree with your approach.
Most of my guides start with: what this is, who needs to do this, why you need to do this. If you don’t confirm that people are on the right page doing the right thing for the right reasons, they can go really far in the wrong direction.
Most government websites don’t explain any of this. They just tell you what they want from you to complete the part of the task that concerns them. They don’t bother to treat the task as part of a bigger decision. They just assume that you are here because you know what you are doing.
Re your last paragraph, the UK gov website excels at this. There are landing pages which describe the process, then warnings and caveats, then you can actually fill in the forms.
Eg this is the Google result for renewing your driving licence https://www.gov.uk/renew-driving-licence - click Start Now and you'll see what I mean
As a "power user" this can sometimes feel like it gets in the way but I understand they need to consider everyone
Yes! I draw a lot of inspiration from them. They really set the standard.
UK gov website is great. It looks great and accessible too.
> If you don’t confirm that people are on the right page doing the right thing for the right reasons
Based on this comment I think you would appreciate Every Page Is Page One a lot. The basic idea is that people can and will land on any random page of your docs site, so every page needs to quickly ground them and make it super easy for them decide whether they're on the right path or no. That's where the book title is coming from. Literally any page of your site might be page one for a user.
That’s exactly how I design my content! I work really hard on making sure that every entry point leads to the right path. It’s surprisingly challenging.
Thank you for the book recommendation. I will give it a look.
This is a really good approach I wish more technical docs had. My mind is always questioning why things are done a certain way, which leads me to side quests that slow me down.
This fits the way I like to use LLMs: I always ask them for options, then I decide myself which of those options makes the most sense.
Essentially I'm using them as weird magical documentation that can spit out (incomplete but still useful) available options to guide my decision making at any turn.
I like to think of it as the apprentices working for famous artists like Leonardo. The master would draw the outline/sketch, and then the students would fill in the blanks under supervision. Sometimes, the master would steal ideas from the students.
Smells like reinforcement learning in real life. Master sets ups the task environment, collects samples from students, picks the best and maybe even augments them. Students watch the master and learn... and the cycle continues.
And then the master becomes a grandmaster (unless entropy explosion occurs).
Yea, and it's what ChatGPT does sometimes even if you don't ask it for multiple options. It shows two options and asks you to select the best one. Essentially using customers to help with training.
Would you be willing to give an example of this?
Not exactly the same… But recently I wanted to pick a library in Python or Julia for simulating differential equations using a GPU. So I asked ChatGPT which libraries exist for this (JAX, CuPy, etc.), asked it to generate code to solve e.g. the 2D heat equation on a 1000x1000 grid for 100 time steps using each of those frameworks. Then I stepped in and verified that each code appeared to do the same thing, and proceeded to benchmark their performance on my hardware. Afterwards I had an informed choice of which framework to use for my project, even though ChatGPT gave me the benchmark code instead of the answer.
Similarly I find Bing copilot very handy for exploring problem spaces and their solution spaces. Then i dig/ask deeper and deeper until i understand the solution. It is a quick way to brainstorm without diverting too much, and hence converging, since that tech knows a lot details about a lot of things.
You should actually ask for 3 examples so you can select one.
Here's one: I asked Claude this:
"Options for JavaScript to turn a JPEG into a vector SVG"
Result: https://gist.github.com/simonw/d2e724c357786371d7cc4b5b5bb87...
I ended up building this: https://tools.simonwillison.net/svg-render
More details here: https://simonwillison.net/2024/Oct/6/svg-to-jpg-png/
> I ended up building this:
I'm confused about how you ended up building the opposite of your initial prompt? The initial prompt seemed like puzzle worth solving.
Here's one: if you want it to rewrite something or show you a better way to say something you've already written, just ask for different options. I usually find that mixing what I wanted to write with parts of its suggestions gives me a great result.
I love this. Short, to the point, and insightful. I’m one of those ‘big picture’ type of thinkers. It’s really important to me to just not know the how behind something, but also the why and how it relates to the larger context. I encourage our developers to make liberal use of the Description field in Jira stories and tasks and provide an overview of why we are doing something and how it relates to the bigger picture. Some of them don’t like it I guess, but some are really digging it. I’m happy to provide the big picture behind the project and they are happy with added independence understanding the big picture gives them.
Thanks for sharing. A couple of thoughts.
It seems like it's a lot harder to measure whether your docs are helping people make good decisions than it is to measure whether they are helping people successfully accomplish a task. I think we optimize for task-based/procedural docs because the business needs us to prove our value, and there is a need for this type of documentation, and there are lots of ways to measure and report on it over short timelines. But answering the question of, "Did this docset help someone build the right thing in the right way", I mean...organizations struggle to answer this question about their own products, abstracting that to try and measure the effectiveness of your docs seems super fuzzy.
Which is not to say you can't write docs that do this, just that it seems very hard to use numbers to prove that you have done so. I definitely think I could rank how well different docsets support users who need to make decisions, and I could offer up explanations to support my reasoning, but I don't know how to quantify that for the business.
I wonder how the structure of a docset that is designed to support decisions differs from that of a docset that supports tasks. I expect you'll have the same main categories (conceptual, reference, guides) but maybe a lot more conceptual docs, and more space dedicated to contextualizing the concepts. I would expect to see topics become more interdependent, more cross-references, etc.
Interesting that your first thought here is not, oh, how can I use this to improve the docs I am writing, but it is, how can I prove that this improves the docs I am writing. You seem to live in a though environment.
You're getting a taste of the world that a lot of professional technical writers live in. Everyone seems to intuitively understand that you need docs, and that if you don't invest in docs it probably will be bad for the business, yet at the same time it's hard to concretely show business value. So technical writers are incessantly asked to prove their value, even though the managers subconsciously know that they're important for some reason. Over the years I have come to believe that docs are important simply because it's a primary mechanism for sharing knowledge across the company and to customers. Michelle Irvine has been doing great work quantifying this: https://cloud.google.com/blog/products/devops-sre/deep-dive-...
Thanks for sharing this post from Michelle, just shared it with some leaders at my company!
You're not wrong. Business is a tough environment.
At a gut level the post seems sensible to me, and it does generate a lot of ideas about how I can make my own docs better. That's not enough, though, if I want the folks who think about docs at my org to change their approach.
As the OP states in several other comments, most writers and organizations learn to prioritize task-based documentation. If we want to adopt a better way of doing things, we need to be able to communicate why it's better. It's no different in other disciplines.
Exactly. Or you become an island doing the good but sometimes barely scratching the surface of what could be possible (to the detriment of your users).
Another aspect of this is that it may take you more time to complete your assignments and you get labeled as slow.
In my own personal projects, where I'm free to do whatever I think is best for my users, I will probably adopt "support decisions" as the foundation of my docs strategy.
In the spirit of working with integrity, if I feel that "support decisions" is the best approach for my own projects, then I probably have a duty to bring this strategy into the docs I do for work.
Luckily I don't have short-sighted managers breathing down my neck, but if I had to convince people at work I would go about it like this:
* Explain the logic of the strategy. Supporting decisions just seems to make sense and ring true . The tasks will still get documented, but tasks are just a subset of decision support.
* And then I would provide a long list of examples from support tickets, chat room discussions, etc. where lack of decision support seemed to be the problem. For intellectual honesty I would show the complete list of docs-related support tickets (for example) and then the subset that were related to supporting decisions. If it's a non-trivial percent (maybe 25%) then we should really look into "decision support" more.
* Last, I might provide examples that the stakeholders themselves have faced in their own work. "Remember how difficult it was to decide what CMS to switch to??"
This is what I generally mean by taking an "heuristic approach."
I feel that we need to have a "fuzzy logic" approach to our work.
However, that works best, when the engineer is somewhat experienced.
If they are inexperienced (even if very skilled and intelligent), we need to be a lot more dictatorial.
Thinking in Bets has been one of the most useful books to how I approach software engineering. It’s not even about code, just how to make decisions effectively in limited information environments.
Love that book. Such a powerful idea to phrase your predictions in terms of percentages rather than absolutes. Apparently the Super Bowl anecdote is controversial though? I.e. the conclusions to draw from that anecdote are very debatable.
I don’t remember the specific anecdotes too much, but the lessons make intuitive sense and feel useful.
The one that sticks to mind most is that a good decision can have a bad outcome and that a good outcome doesn’t always mean the decision was good.
I have no idea what you mean by taking a "fuzzy logic" approach to work. Could you expand and explain that a bit please?
Well “fuzzy logic” is kind of a dated term. I don’t think it has been used in software development, for twenty years.
TL;DR, It basically means not having “hard and fast” boundaries, and instead, having ranges of target values, and “rules” for determining target states, as opposed to “milestones,” so targets are determined on a “one at a time” basis.
When we think of future, mostly we think in a deterministic one single point in the future. I would like to think of future as "possible states" rather than just a single point.
This helps me prepare for different scenarios and then build on top of whatever opportunity comes along.
I got reminded of it when I read "target states" and so thought will share it.
I wrote about how I think about the future here: https://jjude.com/shape-the-future/
> "The key to strategy, little Vor," she explained kindly, "is not to choose a path to victory, but to choose so that all paths lead to a victory." —LMB
The term the ancients had for this was paying attention to the "weakest precondition".
When you are playing against an opponent, yes, you need a min-max strategy.
But then you are not, optimizations are exactly what that name sounds. You usually need to max some goal while you min some weakly correlated one, what sounds similar, but you can pick exactly what "preconditions" you will optimize against. You don't need to cover them all.
"Weakest precondition" is a term of art, specifically referring to predicate transformer semantics[0].
I think we must be interpreting that phrase differently?
Otherwise[1] I'd claim the opposite: when playing against an opponent, one ought merely retain an advantage, which is a weaker predicate than even the weakest liberal precondition, but when playing against entropy (the sheer bloody-mindedness, or at least sufficiently advanced ineptitude, of one's users; or the yolo-tude of whatever provided their data; etc.), especially at several GHz on multiple cores, one should ensure the strict WP.
[0] https://en.wikipedia.org/wiki/Predicate_transformer_semantic... (I'm probably missing some subtlety, but for practical purposes I find reading "set" for "predicate" and "relation" for "predicate transformer" suffices)
[1] unless you're one of those (hopefully rare) devs who always produce fault-tolerant systems — under the principle that ultimately users can be relied upon to tolerate the faults.
Ok. I don't think we are talking about different things, and I still think you got it the other way around.
In fuzzy terms (because boolean logic gets crazy with those concepts):
We have success "S", with preconditions "P0, P1, ...", so that S = P0 & P1 & ...
We can map those concepts into their probability, where the probability of success would be "s = p0 * p1 * ...". AFAIK, your rule is that the best place to optimize is the lowest pN.
That would only be true if optimizing for any of those preconditions had similar costs and values. But on business, those things both tend to vary wildly, and the entire thing tends to get dominated by preconditions that you can't control (infinite costs) very quickly once you achieve a minimum of competence.
Also, the formalism doesn't accept changes on the definition of "success". You will get absolutely nowhere in life if you don't constantly change your definition of success, so the formalism is irredeemably wrong by construction.
> AFAIK, your rule is that the best place to optimize is the lowest pN.
We are talking about different things.
A good approach to making decisions in a team context (also works for personal use) is explained by Rich Hickey here: https://www.youtube.com/watch?v=c5QF2HjHLSE
The talks is called "Design in Practice" but is really about making decisions.
"Work is simply whatever we must do to get from one decision to the next." (Venkatesh Rao, Tempo)
I've advocated something similar. Don't just describe the tool at a high level (people often seem to go into marketing mode) - tell the story of what problem it was designed to solve and the trade offs you made along the way. Makes it much easier to place the tool and available options/modes/etc in context and quickly decide whether it's a good fit for you.
I am a bit confused about this advice. Who's decisions? The tool makers? Or the users?
In general, this seems like an oversimplification. It's more useful to first understand what kind of document you are writing: learning, goal-oriented, understanding, or information. [1] It would be annoying to look up the API for a function and get inundated with "decision" information, for example.
1 - https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...
The docs should always be addressing a user need. That does not go away. Neither does Diataxis (the four quadrants of docs that you mentioned). I think this post is striking a chord because it's unsurfacing a blind spot in the two well-known strategies you mentioned. Everyone tries to make user-focused docs and many follow Diataxis, yet we still struggle to get stuff done with docs. Starting from the foundational viewpoint of the "docs should support decisions" might be a way to make docs more useful.
Knowing how people use your system to make decisions is important. I think that knowledge is vital for maintaining, extending, or building a system.
But the article suggests a higher responsibility: you should document your user's decision-making. You should tell them the context, the choices they have to make, and the consequences of their decisions.
I've worked on a "decision support system" with that responsibility and it got really messy, really fast. Humans love to argue about consequences, even 100% absolutely known ones. They also despise automated emails bearing uncertainty, as well as docs demanding binary choices when many more choices are available in reality.
I would hope the book beyond this article raises the concept of control. That is, to document a behavior, you need some guarantee (or enforcement) about that behavior so your documentation remains authoritative. IMO, the lack of authority/control is common, gaping blindspot of writing initiatives like https://www.plainlanguage.gov unfortunately.
Quoting myself from r/technicalwriting discussion on this post:
> Let me rephrase what I think is really important about Baker's idea. The dogma of technical writing education absolutely revolves around focusing on tasks. If we survey a lot of professional technical writers I will bet you that a majority of them believe that "helping users achieve tasks" is a primary goal of documentation, if not THE primary goal. This small quote from Baker is kinda radical (in the Latin sense of "going to the roots"), because it's suggesting that one of our fundamental assumptions is majorly lacking.
For me personally, Baker's idea is fascinating simply because it sets the bar a lot higher than the current status quo of what's expected of technical writing. A lot of docs just assume that it's "mission complete" once a task is documented, and Baker (to me) is suggesting that it's simply not enough. Tasks of course still need to be documented, but tasks are a subset of the information that goes into decisions.
I don't recall Baker's book discussing control in the way you mention. It's a new idea to me, thanks for sharing. One concrete example of control that comes to mind: if a lot of my docs rely on a page from another open source project, and that external page is not good (low quality), then it should probably be my responsibility to improve that doc. Many people might assume that docs external to their site are outside of their responsibility. But if you're really committed to supporting decisions then it doesn't really matter who is hosting the doc. Maybe there's a lot to learn from the ethos of being a good open source citizen in general
Over on r/technicalwriting I'm having a debate with someone regarding whether this is a general principle or not. To be clear, I have no idea how niche or widespread this problem, is. My hunch is that it's a brilliant insight that applies to technical writing in many industries. For now it's just an idea that I think deserves a lot more thought and discussion.
I’d say it’s an interesting phrasing of a general principle, namely the four types of technical documentation. “Preparing people for decisions” is the first and third types (references and explanations) and “guiding people through tasks” is the second and fourth types (instructions and tutorials). IMO!
Every solution to any problem is trivial once the correct problem has been identified.
mostly true, until you have to start looking at the least worse solution
They say you should not judge a book by its cover, but I found it very hard not to [1]. After I found out the book was from 2013 I felt a slight sense of relief.
[1] https://xmlpress.net/publications/eppo/
What's even more ironic is that it's the most profound book about technical writing that I have yet found in my 12-year career.
It also inspired me to deep-dive into how the pages of my docs site relate to each other, which yielded some useful insights: https://technicalwriting.dev/data/intertwingularity.html
(Baker's book led me to Too Big To Know, which in turn led me to the concept of intertwingularity)
Hi. I wrote Too Big to Know, and your post intertwingled me with this thread, these books, and you.
(Note: I'm taking Google Alerts & Ego Salve as an ironic agent of Ted Nelson's concept of intertwingularity.)
I'm afraid I don't follow: what's unusual about the printed cover of the book, and why is the date of publication relevant to your assessment?
It’s ugly, but ugly in a way that was more common 11 years ago.
The damaged, scribbled collage of papers that forms the background image of the cover was a pretty odd design choice IMO: https://xmlpress.net/wp-content/uploads/covers/EPPO-Cover-Fr...
It's surely related to the central thesis of the book (quoted below) but I think there could have been a more appealing way to get that idea across
> What is needed today is the same rigor and discipline professional writers have long brought to making books, but not the same methodology. The book model does not work for the Web or for content consumed in the context of the Web.
Could you apply this to project work?
Instead of track tasks, track decisions.
Might this apply to marketing communications as well?
How profound /s
This is very much not part of the canon of technical writing dogma, so yes it is profound to me. Professional technical writers are trained from day one to assume that the job revolves around task completion.
[flagged]
THIS GENIUS ALBERTO LITERALLY SAVED ME WHEN HE HELPED ME HACKK INTO 2 PHONES WHICH HARD SOME OF MY PICTURES AND I WAS BEING BLACKMAILED. THIS MAN HELPED ME GAIN ACCESS TO BOTH PHONES WITHIN 5 HOURS. I DELETED THE PICTURES MYSELF FROM MY COMPUTER. I ALSO HAD ACCESS TO ALL THE MESSAGES, PICTURES AND VIDEOS ON THIER PHONES. IF YOU NEED HELP, MESSAGE ALBERTO VIA EMAILL: VADIMWEBHACK@ GMAILL,C0M (HE IS ALSO AVAILABLE ON WHATSAPP AND TELEGRAM) THIS MAN ALSO HELPED A FRIEND OF MINE RECOVER BITCOINS SHE LOST FAKE INVESTMENT SCHEME ONLINE. HE OFFERS A LOT OTHER SERVICES I CAN'T TALK ABOUT HERE.