minimum viable documentation viable... · 2018-11-13 · we don’t like software documentation...

@PeterHilton #WriteTheDocs http://hilton.org.uk/

Minimum Viable

Documentation

http://hilton.org.uk/

What’s wrong with

software system

documentation?

2@PeterHilton •

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 •

README-Driven

Development

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 •

http://tom.preston-werner.com/2010/08/23/readme-driven-development.html

Why doesn’t software

always have a good

README?

6@PeterHilton •

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.


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


Other suggestions


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

Yet more suggestions


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

The README is (the short version of)

the complete system

documentation12@PeterHilton •

Three questions to ask about any tool


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/

https://vanguard-method.net/library/systems-principles/three-questions-to-ask-about-any-tool/

README Maturity Model (Lauri Apple)


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

https://github.com/LappleApple/feedmereadmes/blob/master/README-maturity-model.md

Key take-away

We need system documentation,

but we don’t usually need very much.



Minimum Viable

Documentationpart 2: technical writing


Technical writing

techniques

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 •

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.


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

http://stackoverflow.com/a/2705860

http://stackoverflow.com/u/50742

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


http://stackoverflow.com/u/1282219/rob

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


http://stackoverflow.com/u/3434/rob

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 •

Key take-away

Technical writing is not a mysterious black art:

As with other skills, you can learn techniques and improve.



Minimum Viable

Documentation part 3:

principles & practices


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?


Agile documentation

practices

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


Documentation is just another deliverable

(Allan Kelly)


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

Continuous documentation (Gregory Brown)


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

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 •

https://twitter.com/sadserver/status/910376918163353610

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 •

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 •

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

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 •

Agile documentation

principles

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 •

If you release without

documentation, you only

think you’re releasing.

16@PeterHilton •

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.


‘There is no

documentation fairy.’

Allan Kelly

18@PeterHilton •

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.


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.


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.


Special-purpose documentation for specific needs

There are many kinds of documentation that you usually

don’t need. But sometimes you do.


API reference

Architecture diagram

Contributor’s guide

UML diagram

Component inventory

Entity relationship diagram

Data dictionary

Process model

Business rules

Architecture Decision Record

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.


Exercise

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


minimum viable documentation viable... · 2018-11-13 · we don’t like software documentation...

Documents