Presentation by Kristina D.C. Hoeppner at Linux.conf.au in Perth, Australia, on 8 January 2014. Audio available at https://archive.org/details/DocumentationFun20140108

1. Writing
documentation
can
be
fun
Kristina
D.C.
Höppner,
Catalyst
IT
http://www.flickr.com/photos/77909728@N00/2819392649/
kristina@catalyst.net.nz
‧
Presentation:
Creative
Commons
BY-­‐SA
3.0
LCA
2014
‧
Perth
‧
8
January
2014

2. ELLO
H
E IS
Y NAM
M
a
tin
is
Kr

8. Once
upon
a
time

9. Kristina
D.C.
Hoeppner

10. Sphinx
http://www.flickr.com/photos/ephysimon/3136420463/

11. manual.mahara.org

12. 1 reStructured
Text

13. 1 reStructured
Text
commonly
used
images

14. 1 reStructured
Text

15. 1 reStructured
Text
index
generation

16. 1 reStructured
Text
anchor
for
cross-­‐reference

17. 2 Geany

18. 2 Geany
document
structure

19. 2 Geany
jump

20. 3 Gimp+

21. 3 Gimp+
auto-­‐incrementing
callouts

22. 3 Gimp+
arrows

23. 3 Ubuntu
alternative:
Shutter
arrows
auto-­‐incrementing
callouts

24. 4 Sphinx
make preview Mahara=1.8
kristina@grannysmith:~/code/manual18$
!
sphinx-build -a -D language=en -b html -d build/doctrees
source build/html/en/!
Running Sphinx v1.1.3!
loading translations [en]... locale not available!
loading pickled environment... done!
building [html]: all source files!
updating environment: 0 added, 0 changed, 0 removed!
looking for now-outdated files... none found!
preparing documents... done!
writing output... [100%] todo
!
writing additional files... genindex search!
copying images... [ 3%] images/page_editor/blocks/journals_tagged_new_entry.pncopying images... [ 10%]
images/administration/institution_authentication_plugicopying images... [ 18%] images/administration/
site_statistics_historical_data.copying images... [ 32%] images/page_editor/blocks/
taggedjournalentries_configucopying images... [ 50%] images/page_editor/blocks/
imagegalleryexternal_configucopying images... [ 54%] images/administration/
institution_authentication_ordercopying images... [ 60%] images/page_editor/blocks/
journals_recent_new_entry.pncopying images... [ 67%] images/page_editor/blocks/
creativecommons_configure.pncopying images... [ 67%] images/page_editor/blocks/
recentjournalpost_chooser.pncopying images... [ 70%] images/page_editor/blocks/
recentforumposts_configure.pcopying images... [ 77%] images/page_editor/blocks/
recentjournalpost_configure.copying images... [ 97%] images/page_editor/blocks/
taggedjournalentries_choosercopying images... [100%] images/administration/
pending_registration_approval.png!
copying static files... done!
dumping search index... done!
dumping object inventory... done!
build succeeded.!
magic
happens
!
Build finished. The HTML pages are in build/html/en/.

25. pdf
html
epub

26. 5 Git

27. 6 Launchpad

28. 7 Sphinx+

29. 8 Piwik

30. ≈
92,000
words
*
*
http://www.webwordcount.com/count.php

31. 438
images

32. Links
‣ Mahara
user
manual
online:
http://manual.mahara.org
‣ Mahara
user
manual
git
repro:
https://gitorious.org/mahara/manual
‣ Mahara
user
manual
scripts:
https://gitorious.org/mahara/manual-­‐
packaging
‣ Geany:
http://www.geany.org/
‣ Gimp:
http://www.gimp.org
‣ Gimp
callout
script:
‣ original:
http://registry.gimp.org/node/25086
‣ Mahara-­‐specific:
https://mahara.org/view/view.php?id=60234
‣ Gimp
arrow
script:
http://registry.gimp.org/node/20269
‣ Shutter:
http://shutter-­‐project.org/
‣ Sphinx:
http://www.sphinx-­‐doc.org/
‣ Piwik:
http://piwik.org/

33. Get
involved
www.mahara.org
kristina@catalyst.net.nz
Stay
in
touch
@anitsirk
!
www.catalyst.net.nz