Lessons learned: MDN, sprints, and docs fails

The second conference day took more of the “unconference” format with more open discussions and previously unplanned presentations.

Janet Swisher came back to the stage with a presentation on web-related docs, speaking about the tenth anniversary of Mozilla Developer Network (MDN): history throughout three platform eras, the lessons learned and fruits of hard work reaped. The important point mentioned was the time spent on community engagement and Mozilla‘s communication with the community, which was hugely underestimated at a certain point. Now, Mozilla has focused on better tooling and onboarding, has set up virtual meetings for contributors etc. to improve the integrity within the community and to get the activities more organized.

oh-lib-8-exported Based on his experience, Shaun McCance set the key criteria to turn a sprint into a success, including the number of participants, number of days, organization principles, and tools to make such meetings worthwhile. Setting the rules and environment correctly leads to a productive sprint/hackfest/meetup. I assume it’s also a strong leader drafting an agenda and keeping an eye on the progress made. Luckily, The GNOME docs team has Kat for that 🙂

oh-lib-1-exportedDocumentation fails and a manual to avoid them is exactly what a technical writer needs to grasp. Warren Block went through his years worth of experience with writing documentation and mistakes he learned from. Among the fails mentioned, there was missing context, too much information, fragmented documentation, as well as the lack of documentation testing.

The afternoon session was open to discussions, another spontaneous presentation on getting involved with UBUNTU docs – great noobie’s perspective, BTW! We also talked about systematic reviews, involving paid contributors, and other related topics.

Jason Porter and Shaun McCance spoke at OH

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.

oh-lib-2-exportedI 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.

oh-lib-3-exportedShaun 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/


I’m attending Open Help 2015!

I’m going to spend the upcoming five days in Ohio, Cincinnati at the Open Help Conference & Sprints 2015. (Read more on Shaun McCance’s event at https://conf.openhelp.cc/.)

What are my goals?

To attend the conference talks to learn more about:

  • AsciiDoc, the lightweight markup language;
  • Ducktype and Mallard;
  • a sociotechnical system (MDN), developer documentation, and development of a community;
  • docs failures and the ways to avoid them.

To actively participate in the GNOME Hackfest to:

  • assist to improve the content of the GNOME docs upstream project;
  • improve my practical writing skills and docs planning.

What are my expectations?

  • Number of culture shocks as this is my very first time outside Europe (Experienced a number of them already on my way here: Czech Republic (Brno) –> Austria (Vienna) –> The Netherlands (Amsterdam) –> Minnesota (Minneapolis) –> Northern Kentucky (Cincinnati/Northern Kentucky International Airport) –> Ohio (Cincinnati).)
  • From the professional point of view, new perspectives, new ideas, new docs formats, new and well-known faces, familiar and new topics, lively discussions, collaboration and sharing!

I’d like to thank the GNOME Foundation for sponsoring my attendance to this conference. I’d especially like to thank Shaun McCance, for his enthusiasm and power to bring the community people together!