Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation...
Transcript of Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation...
![Page 2: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/2.jpg)
What’s wrong with
software system
documentation?
2@PeterHilton •
![Page 3: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/3.jpg)
We don’t like software documentation when it’s
1. Time-consuming
2. Hard
3. Wrong
4. Messy
5. Too long
6. Missing
7. Unversioned
8. Incomplete
9. Neglected
10.Boring
3#WriteTheDocs • @PeterHilton •
![Page 4: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/4.jpg)
README-Driven
Development
![Page 5: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/5.jpg)
README Driven Development
‘… we have projects with short, badly written, or
entirely missing documentation…
‘There must be some middle ground between reams of
technical specifications and no specifications at all. And in fact there is.
‘That middle ground is the humble README.’
http://tom.preston-werner.com/2010/08/23/readme-driven-development.html 5#WriteTheDocs • @PeterHilton •
![Page 6: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/6.jpg)
Why doesn’t software
always have a good
README?
6@PeterHilton •
![Page 7: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/7.jpg)
Group exercise (5 minutes)
1. Pick the top ten things to include in a README…
2. Write one section heading per sticky note.
3. Number your README sections 1 to 10 in order of
importance.
4. Stick your notes in a column on the whiteboard.
5. Choose one person per group to present your top 10.
7#WriteTheDocs • @PeterHilton •
![Page 8: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/8.jpg)
Peter’s (current) top 10 README sections
1. What it is
2. Purpose
3. Features
4. Usage/examples
5. Installation
6. Asking questions
7. Building from source
8. Contributing
9. Authors/maintainers
10. License
8#WriteTheDocs • @PeterHilton •
![Page 9: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/9.jpg)
Other suggestions
9#WriteTheDocs • @PeterHilton •
How it works
Status (does it work?)
Troubleshooting
Known issues/bugs
Reporting bugs
Testing
FAQ
Security
Background
Alternatives
Target users - who it’s for
Scope & limitations
Constraints
Hardware requirements
Deployment
Prerequisites
![Page 10: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/10.jpg)
Yet more suggestions
10#WriteTheDocs • @PeterHilton •
Platforms
Architecture
Components
Physical structure
Inputs & outputs
Algorithm choices
Lessons learned
Jargon
Code of conduct
Version
Change log
Copyright information
Contributors
To do list
Further information
![Page 11: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/11.jpg)
![Page 12: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/12.jpg)
The README is (the short version of)
the complete system
documentation12@PeterHilton •
![Page 13: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/13.jpg)
Three questions to ask about any tool
13#WriteTheDocs • @PeterHilton •
1. Who invented this tool?
2. What problem was he/she trying to solve?
3. Do I have that problem?
‘Many people […] are prone to believing the people who
developed the tools have done their thinking for them’
https://vanguard-method.net/library/systems-principles/three-questions-to-ask-about-any-tool/
![Page 14: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/14.jpg)
README Maturity Model (Lauri Apple)
14#WriteTheDocs • @PeterHilton •
Level One: ‘The Code is the Documentation’
Level Two: Bare-Minimum README
Level Three: Basic README
Level Four: README with purpose
Level Five: Product-oriented README
https://github.com/LappleApple/feedmereadmes/blob/master/README-maturity-model.md
![Page 15: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/15.jpg)
Key take-away
We need system documentation,
but we don’t usually need very much.
15#WriteTheDocs • @PeterHilton •
![Page 16: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/16.jpg)
@PeterHilton #WriteTheDocs http://hilton.org.uk/
Minimum Viable
Documentationpart 2: technical writing
![Page 17: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/17.jpg)
Technical writing
techniques
![Page 18: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/18.jpg)
Checklist of technical writing techniques
1. Start with the ‘why?’ - explain benefits up-front
2. Examples before definitions
3. Just-in-time, not just-in-case
4. Teach this stuff!
5. Don’t humiliate the reader
6. Handle or declare new concepts
7. ‘So what and why do I care?’3#WriteTheDocs • @PeterHilton •
![Page 19: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/19.jpg)
Exercise (in pairs)
1. Review the checklist on the handout.
2. Read the answers to the Stack Overflow question.
3. Use the checklist to find opportunities to improve the
text.
4. Highlight the text and mark it with the checklist number.
4#WriteTheDocs • @PeterHilton •
![Page 20: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/20.jpg)
A monad is a data type that encapsulates a value and to which essentially two operations can be applied: • return x creates a value of the
monad type that encapsulates x • m >>= f (read it as ‘the bind
operator’) applies the function f to the value in the monad m
That’s what a monad is. There are
a few more technicalities, but basically those two operations define a monad. The real question is what a monad does, and that depends on the monad — lists are monads, Maybes are monads, IO operations are monads. All that it means when we say those things are monads is that they have the monad interface of return and >>=.
Stack Overflow answer stackoverflow.com/a/2705860 by Chuck stackoverflow.com/u/50742 - CC BY-SA 3.0
![Page 21: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/21.jpg)
In OO terms, a monad is a fluent container. The minimum requirement is a
definition of class <A> Something that supports a constructor Something(A a) and at least one method Something<B> flatMap(Function<A, Something<B>>). Arguably, it also counts if your
monad class has any methods with signature Something<B>
work() which preserves the class’s rules -- the compiler bakes in flatMap at compile time. Why is a monad useful? Because
it is a container that allows chain-able operations that preserve semantics. For example, Optional<?> preserves the semantics of isPresent for Optional<String>, Optional<Integer>, Optional<MyClass>, etc. […]
Stack Overflow answer stackoverflow.com/a/40876132 by Rob stackoverflow.com/u/1282219 - CC BY-SA 3.0
![Page 22: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/22.jpg)
You should first understand what a functor is. Before that, understand higher-order functions. A higher-order function is simply a function that takes a function as an argument. A functor is any type construction T for which there exists a higher-order function, call it map, that transforms a function of type a -> b (given any two types a and b)
into a function T a -> T b. This map function must also obey the laws of identity and composition such that the following expressions return true for all x, p, and q (Haskell notation): map id = idmap (p . q) = map p . map q
For example, a type constructor called List is a functor if it comes equipped with a function of type (a -> b) -> List a -> List b
Stack Overflow answer stackoverflow.com/a/143132 by Apocalisp stackoverflow.com/u/3434 - CC BY-SA 3
![Page 23: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/23.jpg)
More techniques (for longer text)
1. ‘What are you trying to say here?’
2. ‘Give three big take-aways!’
3. Get to the ‘how’
4. Don’t ask the reader to rewind
5. ‘What are you trying to say? Write that down!’
6. Don’t count words
7. Avoid cheerleading - say why it’s better8#WriteTheDocs • @PeterHilton •
![Page 24: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/24.jpg)
Key take-away
Technical writing is not a mysterious black art:
As with other skills, you can learn techniques and improve.
9#WriteTheDocs • @PeterHilton •
![Page 25: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/25.jpg)
@PeterHilton #WriteTheDocs http://hilton.org.uk/
Minimum Viable
Documentation part 3:
principles & practices
![Page 26: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/26.jpg)
Agile software development documentation
From a lean software development perspective,
documentation is waste. Minimum Viable Docs FTW!
How do you include documentation in agile development?
2#WriteTheDocs • @PeterHilton •
![Page 27: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/27.jpg)
Agile documentation
practices
![Page 28: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/28.jpg)
Documentation practices
1. Documentation is just another deliverable
2. Continuous documentation
3. Architecture Decision Records
4. Docs as Code
5. Behaviour-Driven Development with Gherkin
6. Documentation-Driven Development
4#WriteTheDocs • @PeterHilton •
![Page 29: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/29.jpg)
Documentation is just another deliverable
(Allan Kelly)
5#WriteTheDocs • @PeterHilton •
1. Treat documentation like any other deliverable
2. Write and deliver documentation on request.
3. Prioritise documentation against all other work: ‘If someone is prepared to displace other work for
documentation then it is worth doing.’
https://www.allankellyassociates.co.uk/archives/1595/documentation-is-another-deliverable
![Page 30: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/30.jpg)
Continuous documentation (Gregory Brown)
6#WriteTheDocs • @PeterHilton •
1. Keep an unedited journal of your daily work.
2. Periodically review your notes.
3. Categorise and summarise recurring themes.
4. Publish structured notes, e.g. on a wiki.
5. Do not develop your own tool!
6. Iterate everything.
https://www.oreilly.com/ideas/an-efficient-approach-to-continuous-documentation
![Page 31: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/31.jpg)
Architecture Decision Records (Michael Nygard)
1. Concisely record each architecturally significant decision.
2. Use sequential numbering and consistent titles, e.g.‘ADR 1: Deployment on Ruby on Rails 3.0.10’
3. Document context, decision, status, and consequences.
4. Write-once: add new records to replace old ones.
5. Read all records to ‘load’ the current state(it’s like event sourcing for documentation)
http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions 7#WriteTheDocs • @PeterHilton •
![Page 32: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/32.jpg)
https://twitter.com/sadserver/status/910376918163353610
![Page 33: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/33.jpg)
Docs as Code (Eric Holscher)
1. Use the same tools for docs that you use for code: issue tracker, version control, mark-up, review, tests, etc.
2. Use the development team’s workflows.
3. Integrate docs development with the product team.
4. Adopt shared ownership of documentation.
5. Allow any team member to write the first draft.(Relevant for user documentation as well as system docs)
http://www.writethedocs.org/guide/docs-as-code/ 9#WriteTheDocs • @PeterHilton •
![Page 34: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/34.jpg)
Behaviour-Driven Development with Gherkin(Seb Rose)Collaborate - start with a conversation between developers,
testers and business.
Capture the collaboration - record the conversation,
including concrete examples, in Gherkin feature files.
Drive out behaviour with automated tests - execute the
Gherkin test specifications
https://cucumber.io/docs/reference 10#WriteTheDocs • @PeterHilton •
![Page 35: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/35.jpg)
Feature: Refund item
Scenario: Jeff returns a faulty microwave Given Jeff has bought a microwave for $100 And he has a receipt When he returns the microwave Then Jeff should be refunded $100
https://cucumber.io/docs/reference
![Page 36: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/36.jpg)
Documentation Driven Development (Isaac Z. Schlueter)1. Write the README.md file before you write any code.
2. Include example code in the README.
3. Copy the example code into an automated test.
4. Write the code and make it work.
5. Update the docs before you update the code, and repeat.
http://blog.izs.me/post/161633971373/documentation-driven-development 12#WriteTheDocs • @PeterHilton •
![Page 37: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/37.jpg)
Agile documentation
principles
![Page 38: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/38.jpg)
Documentation principles
1. Docs or it didn’t happen!
2. Minimum viable documentation by default
3. Documentation is just another deliverable
4. Sustainable documentation
5. Hard-to-document may indicate poor design
6. Use special-purpose documentation for specific needs
7. Technical writing is yet another skill14#WriteTheDocs • @PeterHilton •
![Page 39: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/39.jpg)
If you release without
documentation, you only
think you’re releasing.
16@PeterHilton •
![Page 40: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/40.jpg)
Minimum viable documentation by default
Zero documentation is a half-hearted default plan.
Comprehensive documentation is worse.
Both lead to (different kinds of) waste.
The minimum viable documentation is hardly any - the
information you can’t get any other way - but not none.
17#WriteTheDocs • @PeterHilton •
![Page 41: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/41.jpg)
‘There is no
documentation fairy.’
Allan Kelly
18@PeterHilton •
![Page 42: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/42.jpg)
Documentation is just another deliverable (Allan Kelly)Documentation isn’t free.
Writing documentation takes time away from other work.
Documentation is expensive to write.
Documentation is even more expensive to read.
The only thing worse than documentation that takes too
long to read is documentation that no-one reads.
19#WriteTheDocs • @PeterHilton •
![Page 43: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/43.jpg)
Sustainable documentation
As with software, documentation maintenance costs more
than initial development.
This is misleading: ‘maintenance’ isn’t a separate activity,
it’s just ongoing development.
Documentation whose value is too low to justify its ongoing
development cost is no longer worth having.
20#WriteTheDocs • @PeterHilton •
![Page 44: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/44.jpg)
Hard-to-document may indicate poor design
Software sometimes turns out to be hard to document.
This discovery gives you an opportunity for feedback.
You can compensate for bad design with good
documentation, but you can’t fix it.
21#WriteTheDocs • @PeterHilton •
![Page 45: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/45.jpg)
Special-purpose documentation for specific needs
There are many kinds of documentation that you usually
don’t need. But sometimes you do.
22#WriteTheDocs • @PeterHilton •
API reference
Architecture diagram
Contributor’s guide
UML diagram
Component inventory
Entity relationship diagram
Data dictionary
Process model
Business rules
Architecture Decision Record
![Page 46: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/46.jpg)
![Page 47: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/47.jpg)
Technical writing is yet another skill
On a cross-functional development team, not everyone is
good at visual design.
The same goes for writing about code.
Some people’s education included writing lots of essays.
24#WriteTheDocs • @PeterHilton •
![Page 48: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/48.jpg)
Exercise
![Page 49: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/49.jpg)
Exercise
1. On the handout, draw lines to each practice from the
principles they support - often more than one
2. Add a principle of your own in the empty box
3. Add your favourite practice in the other empty box
26#WriteTheDocs • @PeterHilton •
![Page 50: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/50.jpg)
Other documentation
topics
![Page 51: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/51.jpg)
Reducing the need for documentation with code
& architecture improvements (docs avoidance)
Better naming and cleaner code (fewer code comments)
Automated BDD/acceptance tests (no functional specs)
Automated builds (shorter installation instructions)
Standard architectures (no system diagrams)
Which documentation is impossible to replace with code?28#WriteTheDocs • @PeterHilton •
![Page 52: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/52.jpg)
Production pipelines Hosted documentation
Word processor files !
Wiki, e.g. Confluence
Google Docs
Markdown + GitHub repo
AsciiDoc → HTML + PDF
Markdown + Jekyll
(GitHub Pages)
reStructuredText + Sphinx
(readthedocs.org)
Documentation as a service
(README.io, Corilla, Ardoq)
29#WriteTheDocs • @PeterHilton •
![Page 53: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/53.jpg)
Code comments "
Comments feature in almost all programming languages,
but remain an almost taboo topic.
Developers will go to bizarre lengths to avoid comments
and usually fail to write code so good they don’t need any.
Comments are not the enemy:
meetings are the enemy!
30#WriteTheDocs • @PeterHilton •
![Page 54: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/54.jpg)
Wrap-up
![Page 55: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/55.jpg)
Minimum viable documentation
We need system documentation,but we don’t usually need very much.
Technical writing is not a mysterious black art:you can learn new techniques and improve.
There are many new practices to replace old approaches; these practices have principles in common.
32#WriteTheDocs • @PeterHilton •
![Page 56: Minimum Viable Documentation Viable... · 2018-11-13 · We don’t like software documentation when it’s 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned](https://reader034.fdocuments.net/reader034/viewer/2022042303/5ece9300646b3a36ef41f497/html5/thumbnails/56.jpg)
@PeterHilton #WriteTheDocs http://hilton.org.uk/http://hilton.org.uk/presentations/documentation-workshop
Ask for details about this workshop at your company
@PeterHilton #WriteTheDocs