Self-Documenting Coders: Writing Workshop for Devs Heidi Waterhouse
History of Technical documentation
- Linear Writing
- On Paper, usually books
- Emphasis on understanding and doing
- Task-based writing
- Early 90s
- DITA
- Concept, Procedure, Reference
- Object-orientated writing
- High art for of tech writers
- Content as code
- Only works when compiled
- Favoured by tech writers, translated. Up to $2000 per seat
- Guerilla Writing
- Stack Overflow
- Wikis
- YouTube
- frustrated non-writers trying to help peers
- Search-first writing
- Every page is page one
- Search-index driven
Writing Words
- 5 W’s of journalism.
- Documentation needs to be tested
- Audiences
- eg Users, future-self, Sysadmins, experts, End users, installers
- Writing Basics
- Sentences short
- Graphics for concepts
- Avoid screencaps (too easily outdated)
- User style guides and linters
- Accessibility is a real thing
- Words with pictures
- Never include settings only in an image ( “set your screen to look like this” is bad)
- Use images for concepts not instructions
- Not all your users are readers
- Can’t see well
- Can’t parse easily
- Some have terrible equipment
- Some of the “some people” is us
- Accessibility is not a checklist, although that helps, it is us
- Using templates to write
- Organising your thoughts and avoid forgetting parts
- Add a standard look at low mental cost
- Search-first writing – page one
- If you didn’t answer the question or point to the answer you failed
- answer “How do I?”
- Indexing and search
- All the words present are indexed
- No false pointers
- Use words people use and search for, Don’t use just your internal names for things
- Semantic tagging and reuse
- Semantic text splits form and content
- Semantic tagging allows reuse
- Reuse saves duplication
- Reuse requires compiling
- Sorting topics into buckets
- Even with search you need some organisation
- Group items by how they get used not by how they get prammed
- Grouping similar items allows serendipity
- Links, menus and flow
- give people a next step
- Provide related info on same page
- show location
- offer a chance to see the document structure
Distributing Words
- Static Sites
- Hosted Sites
- Baked into the product
- Only available to customers
- only updates with the product
- Hard to encourage average user to input
- Knowledge based / CMS
- Useful to community that known what it wants
- Prone to aging and rot
- Sometimes diverges from published docs or company message
- Professional Writing Tools
- Shiny and powerful
- Learning Cliff
- IDE
- Super features
- Not going to happen again
- Paper-ish things
- Essential for some topics
- Reassuring to many people
- touch is a sense we can bond with
- Need to understand if people using docs will be online or offline when they want them.
- Using templates to publish
- Unified look and feel
- Consistency and not missing things
- Built-in checklist
Collaborating on Words
- One weird trick, write it up as your best guess and let them correct it
- Have a hack day
- Ste a goal of things to delete
- Set a goal of things to fix
- Keep track of debt you can’t handle today
- team-building doesn’t have to be about activities
Deleting Words
- What needs to go
- Old stuff that is wrong and terrible
- Wrong stuff that hides right stuff
- What to delete
- Anything wrong
- Anything dangerious
- Anything used of updated in year
- How
- Delete temporarily (put aside for a while)
- Based on analytics
- Ruthlessly
- Delete or update
Documentation Must be
- True
- Timely
- Testable
- Tuned
Documentation Components
- Who is reading and why
- Assuming no one likes reading docs
- What is driving them to be here
- Pre Requisites
- What does a user need to succeed
- Can I change the product to reduce documentation
- Is there any hazard in this process
- How do I do this task
- Steps
- Results
- Next steps
- Test – How do I know that it worked
- If you can’t test i, it is not a procedure
- What will the system do, how does the state change
- Reference
- What other stuff that affects this
- What are the optionsal settings
- What are the related things
- Code and code samples
- Best: code you can modify and run in the docs
- 2nd Best: Code you can copy easily
- Worst: retyping code
- Option
- Why did we build it this way
- What else might you want to know
- Have other people done this
- Lifecycle
Documentation Types
- Instructions
- Ideas (arch, problem space,discarded options, process)
- Action required (release notes, updates, deprecation)
- Historical (roads maps, projects plans, retrospective documents)
- Invisible docs (user experience, microinteractions, error messages)
- Error messages – Unique ID, what caused, What mitigation, optional: Link to report
