6 ms·
Focus on decisions, not tasks
- oatsandsugar 2y ago[flagged]
- deleted 2y ago[deleted]
- Arubis 2y ago"Work is simply whatever we must do to get from one decision to the next." (Venkatesh Rao, Tempo)
- hfifuvthdj 2y agoCould you apply this to project work? Instead of track tasks, track decisions.
- kaycebasques 2y agoOver 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.
- bbor 2y agoI’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!
- yesbut 2y agoHow profound /s
- kaycebasques 2y agoThis 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.
- simonw 2y agoThis 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.
- jiggawatts 2y agoI 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.
- aldanor 2y agoSmells 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).
- gtirloni 2y agoYea, 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.
- A_Venom_Roll 2y agoWould you be willing to give an example of this?
- threatripper 2y agoYou should actually ask for 3 examples so you can select one.
- setopt 2y ago
- smokel 2y agoThey 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/ https://xmlpress.net/publications/eppo/
- kaycebasques 2y agoWhat'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 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)
- dweinberger 2y agoHi. 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.)
- kaycebasques 2y agoOh wow, cool! Thanks for writing the book and nice to meet you. Maybe it's time for Too Big To Know 2.0 given how GenAI is changing the data / information / knowledge / wisdom landscape so much? P.S. I am referencing your concept of networked knowledge in an upcoming conference presentation with my fellow technical writers.
- zahlman 2y agoI'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?
- kaycebasques 2y ago
- ChrisMarshallNY 2y agoThis 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.
- Swizec 2y agoThinking 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.
- kaycebasques 2y agoLove 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.
- Swizec 2y agoI 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.
- RossBencina 2y agoI have no idea what you mean by taking a "fuzzy logic" approach to work. Could you expand and explain that a bit please?
- ChrisMarshallNY 2y agoWell “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.
- chambers 2y agoKnowing 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 https://www.plainlanguage.gov unfortunately.
- kaycebasques 2y agoQuoting 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
- hammock 2y agoMight this apply to marketing communications as well?
- BenFranklin100 2y agoI 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.
- johnathandos 2y agoThanks 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.
- auggierose 2y agoInteresting 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.
- kaycebasques 2y agoYou'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-into-2022-state-of-devops-report-on-documentation https://cloud.google.com/blog/products/devops-sre/deep-dive-...
- nicbou 2y agoI 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.
- switch007 2y agoRe 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 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
- gtirloni 2y agoThis 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.
- kaycebasques 2y ago> 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.
- gushogg-blake 2y agoI'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.
- deleted 2y ago[deleted]
- deleted 2y ago[deleted]
- javajosh 2y agoI 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-of-documentation-and-why-you-need-to-understand-what-they-are-daniele-procida/ https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...
- kaycebasques 2y agoThe 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.
- mmcnl 2y agoEvery solution to any problem is trivial once the correct problem has been identified.
- 123pie123 2y agomostly true, until you have to start looking at the least worse solution
- erichocean 2y agoA 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 https://www.youtube.com/watch?v=c5QF2HjHLSE The talks is called "Design in Practice" but is really about making decisions.
- MalWillis100 2y agoTHIS 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.