References on writing documentation

This page lists the published work the docs.fpgas.online rules are built on, with what each one gives us. It is for someone who wants to read a rule’s source before following or changing the rule. It does not restate the rules. Each row gives a source, what the rules take from it, and one line in the source’s own words.

Page types and structure

Source	What it gives us	In its words
Diátaxis	the four page types; one reader need to a page	“Crossing or blurring the boundaries described in the map is at the heart of a vast number of problems in documentation”
What nobody tells you about documentation, a PyCon AU talk	the problem the four types solve	“Often, it’s not for want of effort … It simply turns out to be not very good”
Every Page is Page One	a page that stands alone; the scope sentences	“Because a reader can arrive at an Every Page is Page One topic from anywhere, the topic must establish its context”
Red Hat modular documentation	fixed headings on a procedure page	“Do not change or embellish these subheadings. Do not create additional subheadings”
The DITA task topic	the fixed order of a task’s parts	“these optional elements in the following order:”
Carroll and van der Meij on minimalism	brevity that serves the task, not brevity for itself	“Brevity is a key element of minimalism, but only because it can facilitate task-oriented activity and learner-initiated reasoning, not as a self-sufficient end in itself”

Style and limits

Source	What it gives us	In its words
Google developer documentation style guide: tables	sources as links, not footnotes	“Avoid using footnotes when possible”
Google technical writing course: documents	scope and audience in the opening lines	“A better document additionally defines its non-scope”
GOV.UK: use clear language	the 25-word sentence	“Try to split up sentences that are over 25 words long”
Microsoft Learn Markdown reference	the limit of two callouts	“Readers tend to skip over them”

Pictures and assembly instructions

Source	What it gives us	In its words
Mayer’s multimedia principles	each picture beside its step	“People learn better when corresponding words and pictures are presented near rather than far from each other on the page or screen”
The Stanford assembly-instruction study, by Heiser and others	one action diagram to a step, at a fixed viewpoint	“significantly reduce assembly time an average of 35% and error by 50%”
Wordless Instructions, on IKEA’s manuals	the finished product first; a test by assembly without text	“a test person manages to assemble the product without any written text in the manual”

Review and upkeep

Source	What it gives us	In its words
Write the Docs: documentation principles	staleness as a defect; one source for each fact	“Consider incorrect documentation to be worse than missing documentation”
iFixit on content quality	a review by someone other than the author	“at least one other team member gives the guide a close look”