====================
Docs Down Under 2017
====================

.. ifnotslides::

   `View slide presentation
   <http://kallimachos.github.io/docs/slides/talks/DDU-2017.html#1>`_

.. ifslides::

   .. rst-class:: title-image

      .. figure:: ../images/kangaroo.png


Welcome
~~~~~~~

.. rst-class:: build

Your hosts for the day:

-  Brian Moss
-  Lana Brindley


Schedule
~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 10 60 30

   * - 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

.. nextslide::

.. list-table::
   :header-rows: 1
   :widths: 10 60 30

   * - 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
~~~~~~~~~~~~~~

.. rst-class:: build

-  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/

.. nextslide::

.. rst-class:: build

-  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?
~~~~~~~~~

.. rst-class:: build

-  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
~~~~~~~~~~~~~~~~~~~

.. rst-class:: build

-  "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
~~~~~~~~

.. rst-class:: build

-  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
~~~~~

.. rst-class:: build

-  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
~~~~~~

.. rst-class:: build

-  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
~~~~~~~

.. rst-class:: build

-  Continuous deployment is great.
-  Contribute your tools work upstream; avoid bespoke solutions when possible.
-  http://kallimachos.github.io/docs/