DSCF0818

Budapest Meetup

Back in April I trav­eled to Budapest. It was my sec­ond time in the city, the first was for Automattic’s 2011 all-company meetup. This time the trip was for a team meetup as well as the Write the Docs con­fer­ence. It was also my first trip with the Fuji X100S. I bought this back in…

Write the Docs: Swizec Teller — What I learned writing a lousy tech book

I’m at Write the Docs today in Budapest and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Swizec wrapped up the sec­ond day of talks. He writes code and books. The lat­ter is the story he told.

The pub­lisher found him after Swizec wrote a short blog post about dis­play­ing dots through d3.js. About a month after the blog post he got a book pro­posal via India. That was Octo­ber of 2012. He quickly read the spec for d3.js and faked his way through an out­line. The “good” news was that the pub­lisher liked the out­line and signed a con­tract for the book.

Then came the writ­ing of a book. He out­lined this as a 4 step process

  1. Think about it. Decide what you can cover in Chap­ter 1 that doesn’t require you to say, “This will be explained later.”
  2. Learn about it. Read the API spec, fig­ure it out.
  3. Code it. Prove that you’ve actu­ally learned some­thing; it’s a means of test­ing your writing.
  4. Write about it. Pull it all together and syn­the­size the experience.

The nice thing is that writ­ing about some­thing you’ve already learned how to code can be extremely easy. Fin­ish­ing the book becomes about repeat­ing that cycle for each and every chapter.

After 66 days and 171 hours of writ­ing Swizec had a 179 page book. He was sick of the book by that time but was happy that it was done. Then came the edit­ing. While he was happy with the book the pub­lisher came back with, “We love it!…but not really.” They wanted him to shorten the book by 60 pages. Swizec then rewrote every­thing. While he didn’t have to make new exam­ples he essen­tially rewrote every piece. He killed the beau­ti­ful turns of phrase, jokes, and other pieces that made writ­ing fun. Through­out the edit­ing process he relied heav­ily upon On Writ­ing Well.

That was the major rewrite. He then did another minor rewrite of addi­tional typos and fixes. Unfor­tu­nately then the tech­ni­cal edi­tors got back with their feed­back and sug­gested even fur­ther rewrites to the tech­ni­cal exam­ples in the book. Luck­ily by this point pub­li­ca­tion was so soon he refused to do deep struc­tural changes. The book was pub­lished in Octo­ber of 2013, one year after start­ing. After 12 months and 333 hours it some­how ended up being 194 pages long. It shipped on his birthday.

After pub­li­ca­tion he didn’t get much infor­ma­tion, just a quar­terly report of sales and roy­al­ties. It’s sold about 1,000 copies so far.

Over­all Swizec learned that pub­lish­ers are dif­fi­cult to work with and that books can be the best way to learn a piece of soft­ware. Writ­ing a book is a hard, hum­bling slog and is truly a fight.

Write the Docs: Mikey Ariel — Your Personal Tech-Writing Agile Manifesto

I’m at Write the Docs today in Budapest and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Mikey’s talk took the con­cepts of agile soft­ware devel­op­ment and focused on how they can apply to writ­ing. She works at Red Hat and lives in the Czech Repub­lic. In a pre­vi­ous role she was a scrum mas­ter in an agile environment.

Mikey started her talk with a brief back­ground or his­tory of agile devel­op­ment. Tra­di­tion­ally soft­ware devel­op­ment relied upon a water­fall process. While this process worked well for phys­i­cal fac­tory pro­duc­tion it didn’t work as well for dig­i­tal soft­ware. All of a sud­den we didn’t have time any more. The deliv­ery time for soft­ware had to be faster and faster; users are impa­tient. The shift was toward more incre­men­tal, iter­a­tive devel­op­ment. This led to agile. Agile goes through the design, code, test, ship process mul­ti­ple times rather than in one mono­lithic cycle. The key is to be flex­i­ble and adapt to what­ever envi­ron­ment you work within. There are 4 key prin­ci­ples to agile development:

  1. Indi­vid­u­als and inter­ac­tions over processes and tools. While there is value in processes and tools the peo­ple you work with come first.
  2. Work­ing soft­ware over com­pre­hen­sive doc­u­men­ta­tion. Docs are still okay, though, you just want to ensure they’re gran­u­lar and not monolithic.
  3. Cus­tomer col­lab­o­ra­tion over con­tract nego­ti­a­tion. As a writer you want to hear what the cus­tomer has to say and make docs a first class cit­i­zen in the software.
  4. Respond­ing to change over fol­low­ing a plan. The key is to stay aware of what’s com­ing down the line and ship­ping every day in the code.

The flex­i­bil­ity in this is how agile relates to writ­ing docs. As a writer you’re thrown in to an envi­ron­ment that you must adapt to. Stay­ing ahead of the code helps ensure your docs never get swamped by cur­rent releases.

Write the Docs: Kristof Van Tomme — Keeping trust: Testing documentation as part of a continuous integration process

I’m at Write the Docs today in Budapest and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Kristof, who helped make this con­fer­ence hap­pen, is an evan­ge­list in the Dru­pal com­mu­nity. His talk focused on doc­u­men­ta­tion in a post-agile world. Given the more hec­tic nature of agile soft­ware devel­op­ment ensur­ing that your doc­u­men­ta­tion is up to date is quite dif­fi­cult. You end up main­tain­ing mul­ti­ple ver­sions of doc­u­ments, some­times writ­ing docs for fea­tures which haven’t yet shipped or even been fin­ished in code. You know the docs will fail at some point, the ques­tion is when.

The trick, though, is that devel­op­ers already solved these com­plex­i­ties in the shift to agile devel­op­ment. On the soft­ware side devel­op­ers have auto­mated aspects of QA in order to speed up deploy­ment. Kristof believes we can take that same mind­set to docs. You can do this by either merg­ing docs in to tests or embed­ding tests in to docs. Both are difficult.

In DITA doc­u­men­ta­tion is bro­ken up in to ref­er­ences, tasks, and con­cepts. Ref­er­ences are writ­ten in code or extracted from from code. Com­mon exam­ples are doc­u­men­ta­tion around API func­tions; these become easy to test. Tasks let you doc­u­ment auto­mated exe­cu­tion in your project. Con­cepts let you address places where ter­mi­nol­ogy may change between two ver­sions of your code. Using embed­ded RDFa or a the­saurus extrac­tor you could try and ensure your code and doc­u­men­ta­tion agree.

Kristof also talked a bit about build­ing the ulti­mate user guide to the inter­net. This stems from his project WalkHub. The con­cept is that online tools and sites often require us to absorb too much infor­ma­tion. Luck­ily, though, there is a short­cut; it’s about cog­ni­tive load reduc­tion. Peo­ple have a lim­ited amount of work­ing mem­ory and if you dump too much infor­ma­tion on them they’ll overload.

Write the Docs: Fintan Bolton — The community wrote my docs!

I’m at Write the Docs today in Budapest and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Fin­tan kicked off the longer talks after light­ning talks. He works as a writer at Red Hat and focused on where com­mu­nity doc­u­men­ta­tion meets prod­uct doc­u­men­ta­tion. His talk explored whether a com­mu­nity could write your proper, offi­cial documentation.

As writ­ers we never have enough time to pur­sue all the projects we want to accom­plish. The com­mu­nity Fin­tan works with has writ­ten about 1,000 pages of the 6,000 total pages of doc­u­men­ta­tion. While the community’s doc­u­men­ta­tion lives in a Con­flu­ence Wiki the offi­cial Red Hat doc­u­men­ta­tion needs to live in Doc­Book. The com­mu­nity wiki gives a low bar­rier to con­tribut­ing an pairs instant pub­li­ca­tion with plain text edit­ing. Doc­Book, on the other hand, is more com­plex to edit but presents good for­mats for archiv­ing docs and has a rich markup vocabulary.

They rely upon a com­mer­cial tool to con­vert the Con­flu­ence wiki infor­ma­tion to Doc­Book. Sim­ply con­vert­ing the con­tent, though, isn’t enough. There’s still a dis­tinc­tion between com­mu­nity doc­u­men­ta­tion and cor­po­rate doc­u­men­ta­tion. What they run in to in this process is:

  • Vari­able qual­ity in com­mu­nity docs. There might be dif­fer­ent for­mat­ting, styles, or more.
  • Com­mu­nity doc­u­men­ta­tion fre­quently has dif­fer­ent versioning.
  • Com­mu­nity doc­u­men­ta­tion may have inap­pro­pri­ate con­tent, links, and more. Things like untested fea­tures you’re not yet supporting.

Given that, Red Hat goes through a process for syn­chro­niz­ing their com­mu­nity and prod­uct docs. They use a sep­a­rate repos­i­tory for each and main­tain a series of snap­shots for both sets. These are stored in their ver­sion con­trol sys­tem. Ide­ally these sets stay close to each other. In real­ity, though, after a cou­ple releases the two sets diverge quite a bit.

What they’ve done is sim­ply com­pare the com­mu­nity docs with an auto­mated diff tool and then merge those changes in to the cur­rent prod­uct docs. It trades a bit of man­ual labor for less diver­gent doc sets.

Ulti­mately bring­ing in com­mu­nity doc­u­men­ta­tion from open source projects is tough, but worth it. The dif­fer­ent for­mats, tone, and nec­es­sary infor­ma­tion can take time to sort out but even­tu­ally gives you a much stronger base to work from.

Write the Docs: Elizabeth Urello — Blogging as Non-Traditional Support Documentation

I’m at Write the Docs today in Budapest and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Eliz­a­beth wrapped up the talks before lunch in talk­ing about blog­ging as non-traditional sup­port docs. For WordPress.com the tra­di­tional doc­u­men­ta­tion exists as a sprawl­ing sup­port site with hun­dreds of docs. The sup­port staff pri­mar­ily writes and main­tains the docs.

Blogs help doc­u­ment things for read­ers in a few ways. First, they let read­ers sub­scribe and pro­vide an incre­men­tal intro­duc­tion to var­i­ous top­ics. Email updates are occa­sional prompts to keep learn­ing for new users.

Sec­ond, it turns doc­u­men­ta­tion in to con­ver­sa­tion. Read­ers can com­ment on the posts and inter­act directly with staff. That feed­back loop can help guide future iterations.

Also, blogs have authors. Users know who the writer of a doc­u­ment is. It can help cre­ate an ongo­ing rela­tion­ship between staff and users that’s based around cre­ativ­ity and proac­tive sup­port rather than merely trou­bleshoot­ing. That aspect can also expand the pool of peo­ple writ­ing your docs. Peo­ple have a bet­ter frame of ref­er­ence for how to write a blog post than a sup­port doc. At WordPress.com this means that the per­son launch­ing a new fea­ture or theme writes the ini­tial sup­port doc as well as the announce­ment post.

Blogs also give you a fresh start to your doc­u­men­ta­tion. It’s eas­ier to start a new blog than to over­haul an exist­ing sup­port site which means exper­i­men­ta­tion comes more eas­ily. What you learn from blog­ging can then be applied to the documentation.

The two main ways this hap­pens is through the main News Blog and through the Daily Post. The News Blog focuses on new fea­ture announce­ments, com­pany activ­ity, and high­light­ing less pop­u­lar or well known fea­tures. The Daily Post hosts weekly writ­ing and photo chal­lenges as well as focus­ing on more task-based instruc­tion. In the last cou­ple of months the Edi­to­r­ial Team has also put together a cou­ple ebooks that focus on things like Pho­tog­ra­phy 101. The mate­r­ial comes straight from blog posts over the months and acts as a great resource for new users.

An exam­ple Eliz­a­beth high­lighted was the Zero to Hero pro­gram started in Jan­u­ary. Along­side each chal­lenge there was an open forum thread for ques­tions and com­ments. By the end of the month par­tic­i­pants pub­lished 48 times as often as a ran­domly selected con­trol group.

Write the Docs: Christine Burwinkle — Pairing with designers to create a seamless user experience

I’m at Write the Docs today in Budapest and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Chris­tine works at Atlass­ian, mak­ers of Jira and other soft­ware tools for soft­ware devel­op­ers. Their design team has grown from 5 to 30 over the last cou­ple of years. On the whole Atlass­ian has focused a lot on the user expe­ri­ence of their prod­ucts. Tra­di­tion­ally their tech writ­ing has played a more for­mal or tra­di­tional role. They saw an oppor­tu­nity to work together toward shared goals. Both are try­ing to reach users and give them a really great expe­ri­ence, they just use dif­fer­ent tools.

A few of the design prin­ci­ples the docs team brought over to their work were to be famil­iar, to grow with users, and to give clar­ity to users. Those drive the deci­sions their design team makes. They real­ized those goals are eas­ily adapted to doc­u­men­ta­tion. Per­sonas also play a role for both their design and docs team. The design team did a year­long project to develop those per­sonas. These make it easy for dif­fer­ent teams to have com­mon ground in how to build their soft­ware for their users.

The docs team real­ized in this process that design­ers have access to lots of cus­tomer infor­ma­tion. They have inter­views, site vis­its, usabil­ity tests, usage infor­ma­tion on exist­ing fea­tures, and a long-term roadmap for the prod­uct. All of that can help a docs team build doc­u­men­ta­tion that’s rel­e­vant for users.

The doc­u­men­ta­tion process for Atlass­ian starts in user test­ing. Design­ers test new pro­to­types with users and the docs team uses infor­ma­tion from those tests to guide their doc­u­men­ta­tion edits. They pig­gy­back ana­lyt­ics on to this for hard data as well.

The first tool the docs team bor­rowed from the design team was empa­thy maps. Empa­thy maps help bring focus on the user. You can use them to work­shop how a user might feel in a “before and after” sit­u­a­tion. You take the “after” sit­u­a­tion and work backward.

Another tool they’ve bor­rowed is spar­ring ses­sions. They’re basi­cally a cri­tique ses­sion that brings group think­ing in to design and plan­ning. It’s a check that the goals have been met with a given pro­to­type. The goal is to assure design qual­ity by cri­tiquing design early and often. Prior to a spar­ring ses­sion they send out a draft of the doc as well as a brief or out­line that cov­ers the goals of a doc­u­ment. A few tips they’ve learned the hard way:

  • Time­box, time­box, time­box! Set a timer so you don’t go down rab­bit holes.
  • If your team is given to neg­a­tiv­ity, try a positives-only 5 minutes.
  • Try to make sure every­one is heard. You can use a check­list or give every­one 1 minute to list feedback.
  • Leave with at least 3 action items. The onus is on the writer to take action on these things.

6-ups are another work­shop­ping tool they’ve bor­rowed. They drive focus on ideal solu­tions and get you out of “word-thinking” and can be a good way to build on each oth­ers’ ideas. Some­times the best way to com­mu­ni­cate an idea is to sketch it and really illus­trate what a user will be see­ing for a given feature.

User stores are an addi­tional tool. It’s about fig­ur­ing out how a user is going to go through a prod­uct. It charts a path through goals and actions within a prod­uct. Going through that path can help you spot where users will hit pain points and fall out of the flow.

They made all this hap­pen by find­ing the right projects. They looked for a team that finds value in design and writ­ing as well as a designer who sees the value in docs. It helps to look for a new project that’s run­ning lean and has some momen­tum. Projects that are data-driven are also ben­e­fi­cial as it helps cement and val­i­date the work you’re putting in to these sessions.

Write the Docs: Sebastien Goasguen — Going from Publican to Read the Docs

I’m at Write the Docs today in Budapest and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Sebastien was the first talk after break. He works on Apache Cloud­Stack and is a com­mit­ter to the Apache project.

Apache Cloud­Stack moved from an old doc­u­men­ta­tion tool, Pub­li­can and Doc­Book, to Read the Docs. They wanted to bring in a greater sense of com­mu­nity with their doc­u­men­ta­tion and make it more accessible.

The old tool, Pub­li­can, is a build tool for doc­u­men­ta­tion writ­ten in the Doc­Book for­mat. Doc­Book itself is a XML schema suited for books and papers; it’s not nec­es­sar­ily meant for web-based docs. The edit­ing tools, though, are either tech­ni­cal like vi or expen­sive. For an open source project that’s a no-go. They were also run­ning in to issues around local­iza­tion, inter­na­tion­al­iza­tion, host­ing, and attract­ing new writers.

Using Read the Docs they were able to move toward using reStruc­tured­Text for writ­ing. It’s an easy-to-read, WYSIWYG plain text markup syn­tax parser. The prob­lem, though, is that they had 40,000 lines of XML to trans­form in to reStruc­tured­Text. Their life­saver was pan­doc. This let them con­vert all the files with­out need­ing to rewrite everything.

Sphinx allows them to build their doc­u­men­ta­tion sites and projects. The host­ing is han­dled through Read the Docs. One of the killer fea­tures for them was the but­ton on each doc that let peo­ple edit on GitHub. Given that Apache CloudStack’s goal was to increase their con­trib­u­tor base this was vital. It dropped the bar­rier to entry for new con­trib­u­tors. They’re now start­ing to see drive-by con­tri­bu­tions to docs, which is great.

The one last hur­dle for them is trans­la­tion. With large com­mu­ni­ties in China and Japan it’s key for the project to make trans­la­tion easy. Hand­ily, with Sphinx, they can do this. They use the same tool that Markus talked about yes­ter­day. They now have more peo­ple con­tribut­ing trans­la­tions than they do documentation.

Ulti­mately chang­ing doc­u­men­ta­tion for­mat gave Apache Cloud­Stack docs which were good look­ing, easy to con­tribute to, sup­port­ive of local­iza­tion, and much much more.