Focus on decisions, not tasks
technicalwriting.dev
technicalwriting.dev
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.
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
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.
Thank you for the book recommendation. I will give it a look.
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.
And then the master becomes a grandmaster (unless entropy explosion occurs).
"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'm confused about how you ended up building the opposite of your initial prompt? The initial prompt seemed like puzzle worth solving.
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.
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.
Another aspect of this is that it may take you more time to complete your assignments and you get labeled as slow.
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??"
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.
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.
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.
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 term the ancients had for this was paying attention to the "weakest precondition".
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.
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.
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.
We are talking about different things.
The talks is called "Design in Practice" but is really about making decisions.
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...
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.
> 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
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)
(Note: I'm taking Google Alerts & Ego Salve as an ironic agent of Ted Nelson's concept of intertwingularity.)
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.
Instead of track tasks, track decisions.