[HN Gopher] Focus on decisions, not tasks
___________________________________________________________________
Focus on decisions, not tasks
Author : kaycebasques
Score : 40 points
Date : 2024-10-18 17:58 UTC (5 hours ago)
(HTM) web link (technicalwriting.dev)
(TXT) w3m dump (technicalwriting.dev)
| Arubis wrote:
| "Work is simply whatever we must do to get from one decision to
| the next." (Venkatesh Rao, Tempo)
| kaycebasques wrote:
| 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.
| yesbut wrote:
| How profound /s
| kaycebasques wrote:
| 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.
| simonw wrote:
| 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.
| jiggawatts wrote:
| 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.
| smokel wrote:
| 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/
| kaycebasques wrote:
| 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)
| zahlman wrote:
| 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?
| kaycebasques wrote:
| 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.
| travisjungroth wrote:
| It's ugly, but ugly in a way that was more common 11 years
| ago.
| ChrisMarshallNY wrote:
| 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.
| Swizec wrote:
| 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.
| kaycebasques wrote:
| 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.
| Swizec wrote:
| 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.
| RossBencina wrote:
| I have no idea what you mean by taking a "fuzzy logic" approach
| to work. Could you expand and explain that a bit please?
| chambers wrote:
| 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.
| kaycebasques wrote:
| 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. When I
| reflect back on the kinds of questions that come up in chat
| rooms and support tickets, as well as my own struggles to get
| something done, a non-trivial percentage are related to
| "needing more information to make a decision". 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. If the
| "focus on decisions" idea takes off, I would guess that we're
| collectively in the "crawl first then walk" phase. People just
| need to get hands-on experience with the "decision support"
| worldview ("crawling") and then we might be in a better
| position to make progress on control as you describe it
| ("walking").
|
| 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 wrote:
| Might this apply to marketing communications as well?
___________________________________________________________________
(page generated 2024-10-18 23:00 UTC)