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

Writing  documentation  can  be  fun  

Kristina  D.C.  Höppner,  Catalyst  IT

HELLO

MY NAME IS

Kristina

Once  upon  a  time

Kristina  D.C.  Hoeppner

Sphinx

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

manual.mahara.org

reStructured  Text1

reStructured  Text1

commonly  used  images

reStructured  Text1

reStructured  Text1

index  generation

reStructured  Text1

anchor  for  cross-­‐reference

Geany2

Geany2

document  structure

Geany2

jump

3 Gimp+

3 Gimp+

auto-­‐incrementing  callouts

3 Gimp+arrows

Ubuntu  alternative:  Shutter3

auto-­‐incrementing  callouts

arrows

kristina@grannysmith:~/code/manual18$ make preview Mahara=1.8!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.!!Build finished. The HTML pages are in build/html/en/.

Sphinx4

magic  happens

pdf        html        epub

Git5

Launchpad6

Sphinx+7

Piwik8

≈  92,000  words

*  http://www.webwordcount.com/count.php

*

438  images

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

Links

www.mahara.org Get  involved

Stay  in  touch

kristina@catalyst.net.nz  

@anitsirk  

!

www.catalyst.net.nz