Docs Down Under 2017

View slide presentation

Welcome

Your hosts for the day:

  • Brian Moss

  • Lana Brindley

Schedule

Time

Title

Speaker

10:40

Welcome

Brian Moss

11:15

Quiz

Lana Brindley

12:00

Prize Session

12:20

LUNCH

13:20

Stephen King's practical advice for tech writers

Rikki Endsley

14:00

Sorting out the mess: How information architecture can help

Darren Chan

14:20

Kernel documentation: What we have and where it's going

Jonathan Corbet

Time

Title

Speaker

15:00

TEA

15:40

Writing less, saying more: UX lessons from the small screen

Claire Mahoney

16:20

Effective docs writing: Practical writing style explained with computer science

Joe Robinson

16:40

Helping caterpillars fly

Nicola Nye

17:20

END

Docs like code

  • Apply software development tools and techniques to documentation development.

  • Keep docs close to code using a source file concept.

  • Automate and integrate documentation builds so you can focus on content.

  • http://docslikecode.com/

  • Not a new idea in open source communities, but the practice is still evolving.

  • Writers have more opportunity to be involved with infrastructure.

  • Writers know their development requirements and the needs of their users.

  • Encourages contributions from developers.

Imposter?

  • Writers may not have a background in software development and may be hesitant to mess around with the tool chain.

  • But we are called technical writers for a reason.

  • Give it a go. Struggling to get things working is a great way to learn.

  • We don't always have access to a developer, and it is empowering to solve problems with code.

  • What's the worst that could happen?

  • sphinxmark (https://kallimachos.github.io/sphinxmark/).

Think like a writer

  • "We can teach you technology; we can't teach you how to write."

  • Writers have a highly useful skill set, so use it!

  • There are four phases:

    • research

    • draft

    • review

    • publish

Research

  • Gather requirements before you begin.

  • Get approval.

  • Get consensus from your colleagues for changes that affect work flow or UX.

  • Search for existing solutions before you start coding; there's a reasonable chance someone else has had the same problem.

  • Google and Stack Overflow are your friends.

  • Reading documentation is a pretty good idea too.

  • Simplify as much as possible.

Draft

  • Think about structure; changing later is hard.

  • You have never gone so far down one path that you can't try another.

  • Work on a branch, not on production.

  • Code with reuse in mind; structure your work with consideration for future changes.

  • Code consistently; adopt an upstream style guide.

  • Document your work. You will thank yourself later.

Review

  • Automated testing and continuous integration are great, although they do have limitations.

  • Ask other writers to test your work.

  • Ask a friendly neighborhood developer to have a look at your code.

  • Advertise your changes.

Publish