The Open Help’s first day talks focused on docs formats. Check the schedule [1] and abstracts [2].
Janet Swisher kicked off the morning session with a workshop on Mozilla Developer Network (MDN). Following the getting started guide for MDN, everybody got the opportunity to start contributing to Mozilla docs. The guide is comprehensible and very straight-forward, which makes the contributing process super simple. The documentation is in the “wiki pages” format, so the learning process is basically non-existent for a tech writer: sign up and click the “Edit” button to start contributing! The workshop itself triggered a number of style questions comparing newspaper and book heritage. However, the main session on a socio-technical system, MDN, is on tomorrow’s agenda.
I personally appreciated Jason Porter‘s thorough introduction to AsciiDoc and AsciiDoctor. In Red Hat, AsciiDoc is mostly used for non-platform projects, so I, as a Red Hat Enterprise Linux writer, do not use this format actively. AsciiDoc arises from DocBook, uses similar elements and entities as we could see from the syntax features presented in Jason’s slides. However, AsciiDoc is a slim-downed version of DocBook, a lightweight markup language, the number of elements AsciiDoc makes use of is sensible (see for yourself: [3]), which makes it so popular. Surprisingly, though, conversion from DocBook to AsciiDoc and vice versa is not at all trivial and cannot be performed fully automatically.
Shaun McCance talked on his user help project, project Mallard, explaining why the project turned quickly into a success. Mallard is extensible, pluggable, semantic, and simple, which I can second from my own experience from contributing to the GNOME Documentation Project. Nesting attributes and table syntax were discussed in detail.
[1] https://conf.openhelp.cc/2015/schedule
[2] https://conf.openhelp.cc/2015/speakers
[3] http://asciidoc.org/