Top all-time · #14544
Mark Baker
Personal blog · everypageispageone.comwritingcareer
Mark Baker writes Every Page is Page One, a personal blog at everypageispageone.com about writing and career. Since 2016, 5 different Hacker News readers have linked it 6 times. No feed was found, so read it on the site itself.
Too few sampled comments (5) to say how often HN recommends it.?
Why HN links it
HN readers link Mark Baker's site for technical writing, especially the 'every page is page one' principle from his book. Other posts discuss documentation frameworks such as Diátaxis and DITA.
Summarised by Claude from a sample of 5 HN comments that link here. Each comment is marked recommending, critical or neutral (citing without judging); how this works.
Mark Baker's Content Strategy and Technical Communication Blog
Most-linked posts?
- /the-book/2 people · 2 mentions · first linked 2018-08-24
- /2 people · 2 mentions · first linked 2023-07-06
What Hacker News says?
Fails at the first step, for me. WTF is "Total Annihilation"? There's a sort of motto in technical writing: every page is page 1. https://everypageispageone.com/ Don't assume your readers know anything at all. Work out your assumptions and always state them. I was curious, but not enough to do more than a cursory search. Apparently it's some game I've never heard of and am not curious enough about to read an entire…
Comment linking /
on “Total Annihilation, rebuilt for modern computers”Submitted We need constrainable lightweight markup languages as a story · 49 points
HN discussionI'm a technical writer. Diátaxis is similar to DITA: https://www.oxygenxml.com/dita/1.3/specs/archSpec/base/infor... On the other hand, systems like these might miss out on what users actually need. Diátaxis might work for a long time if technical documentation is only used in a documentation platform. However, if the same information could and should be used in more than one place—for example, in a UI, in a documen…
Comment linking /the-book/
on “Diátaxis – A systematic approach to technical documentation authoring”Technical writers call this "information architecture". Hierarchical organization is tough. E.g. if you're working on a docs site, and you have a multi-level nav, what's the best way to organize that nav? Same problem with organizing the directories in a company's intranet. One idea that is influential within the technical writing community is to "treat every page as page one" [1]. Because of Search, you never know…
Comment linking /the-book/
on “Writing Documentation When You Aren't a Technical Writer”There's a great tech writing book called Every Page is Page One [1] that changed how I write docs. Its primary conceit is basically what you've described: every single doc needs to immediately orient its reader, either with an intro paragraph or seamless hyperlinks to relevant background material (or, ideally, both). If the reader lands on a page that isn't right for them, it's the writer's job to leave a trail of b…
Comment linking /
on “My Problem with the Four-Document Model”I go back and forth on the usefulness of Diataxis and related information frameworks—Mark Baker (of EPPO fame) has an interesting series[1] about the DITA equivalent of task, concept, and reference: > If there is a problem with DITA, then, it is not that it lacks a theory of information design. The problem is that many people actually believe that it does have a theory of information design, and that that theory can…
Comment linking /2012/07/28/the-tyranny-of-the-terrible-troika-rethinking-concept-task-and-reference/
on “Beyond OpenAPI”
