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 October 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 Chapter 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. Finishing 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. Throughout the edit­ing process he relied heav­ily upon On Writing Well.

That was the major rewrite. He then did another minor rewrite of addi­tional typos and fixes. Unfortunately 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. Luckily by this point pub­li­ca­tion was so soon he refused to do deep struc­tural changes. The book was pub­lished in October 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.

Overall 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. Writing 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 Republic. 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. Traditionally 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. Individuals 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. Working 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. Customer 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. Responding 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. Staying 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 Drupal 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. References are writ­ten in code or extracted from from code. Common 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. Concepts 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. Luckily, though, there is a short­cut; it’s about cog­ni­tive load reduc­tion. People 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.

Fintan 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 Fintan 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 Confluence Wiki the offi­cial Red Hat doc­u­men­ta­tion needs to live in DocBook. 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. DocBook, 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 Confluence wiki infor­ma­tion to DocBook. Simply 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:

  • Variable qual­ity in com­mu­nity docs. There might be dif­fer­ent for­mat­ting, styles, or more.
  • Community doc­u­men­ta­tion fre­quently has dif­fer­ent versioning.
  • Community 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. Ideally 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.

Ultimately 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.

Elizabeth 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.

Second, it turns doc­u­men­ta­tion in to con­ver­sa­tion. Readers 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. People 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 Editorial Team has also put together a cou­ple ebooks that focus on things like Photography 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 Elizabeth high­lighted was the Zero to Hero pro­gram started in January. Alongside 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.

Christine works at Atlassian, 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 Atlassian has focused a lot on the user expe­ri­ence of their prod­ucts. Traditionally 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. Personas 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 Atlassian starts in user test­ing. Designers 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. Empathy 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:

  • Timebox, 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. Sometimes 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 CloudStack and is a com­mit­ter to the Apache project.

Apache CloudStack moved from an old doc­u­men­ta­tion tool, Publican and DocBook, 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, Publican, is a build tool for doc­u­men­ta­tion writ­ten in the DocBook for­mat. DocBook 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. Handily, 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.

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

Write the Docs: Robert Lehmann — Self-Directed Learning Material

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.

Robert focused on how to write good learn­ing mate­r­ial. We all suf­fer from ed-tech amne­sia, in Robert’s words. There’s a huge body of research on how to teach peo­ple and how they learn mate­r­ial. In research­ing this talk he found that while there’s a huge body of mate­r­ial it is wildly arcane to us as tech­ni­cal people.

Robert works at the Open Tech School where they work to teach stu­dents pro­gram­ming. The work­shops are done col­lab­o­ra­tively with lots of hands-on coaching.

The first step in learn­ing and col­lab­o­rat­ing is defin­ing clear goals. You need to know where you want to go with the mate­r­ial; begin­ning with the end in mind helps greatly. There’s a dif­fer­ence between tuto­ri­als and ref­er­ences. References may seek to exhaus­tively doc­u­ment an API while tuto­ri­als con­sciously explain a sin­gle con­cept with an end goal defined.

Collaboration, though, can kill cohe­sion. With many peo­ple involved you have to actively pro­tect the scope of learn­ing mate­r­ial. At the Open Tech School they have some­one who acts as the cham­pion of learn­ing doc­u­men­ta­tion and they seek keep work tied closely to learn­ing objectives.

When you use the right tools and light­weight markup you can lower the bar­rier to learn­ing. For the Open Tech School this means using Jekyll and host­ing files on GitHub Pages.

One thing that they haven’t found a good solu­tion for is deal­ing with depen­dency hell. When teach­ing peo­ple how to code you run in to issues where the pre­req­ui­sites for solv­ing a given prob­lem can involve set­ting up hand­fuls of other, irrel­e­vant, depen­den­cies. When teach­ing kids they’ve tried using sys­tem images that bun­dle those depen­dency require­ments so stu­dents can write code and have it run right out of the box, mostly.

Another thing they have strug­gled with in their mate­r­ial is the amount of rep­e­ti­tion. Repeating things is good, but at the same time you want to be con­cise so that stu­dents don’t skip over repeated material.

One guide­line that is extremely use­ful for new coaches is to tell them the key­board of stu­dents is made of lava. Too many new coaches can­not sup­press the impulse to just fix one thing for the stu­dent. The prob­lem is that this dis­rupts the student’s flow and atten­tion. On top of that nudg­ing new coaches to use socratic ques­tion­ing can greatly help. Your stu­dents will ben­e­fit if you don’t just give them the answers.

At the Open Tech School they’ve found that feed­back is great but that it’s mostly pos­i­tive from stu­dents. Instead they focus on ask­ing the coaches for feed­back on where stu­dents strug­gle. It helps them spot the gaps and short­com­ings in their doc­u­men­ta­tion and learn­ing material.

Finally, they’ve pub­lished all of their coach­ing guide­lines.

Write the Docs: Tom Christie — Designing MkDocs

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.

Tom started day 2 of talks at Write the Docs. He works as a soft­ware engi­neer at a web devel­op­ment startup in Brighton, UK.

MkDocs is a soft­ware project for pro­duc­ing nice-looking doc­u­men­ta­tion from mark­down files. Tom uses it with a lot of his own open source projects. Previously he han­dled doc­u­men­ta­tion through Sphinx, which Markus talked about yes­ter­day. This uses restruc­tured text for doc­u­men­ta­tion. Writing the actual docs, though, was not the most attrac­tive process.

To help cre­ate more attrac­tive docs with a clearer design Tom started draft­ing docs in Markdown. As he said, “The doc­u­men­ta­tion is really the design of the prod­uct.” Using edi­tors like Mou he was able to cleanly assem­ble and visu­al­ize his doc­u­men­ta­tion. It helps to see what your read­ers will see.

From that expe­ri­ence he decided to tear up the exist­ing tools and start again. Writing a cus­tom lit­tle script he built the doc­u­men­ta­tion for the django REST frame­work. The down­side was that every­thing was hard-wired to this one project; it wasn’t the most reusable piece of code. Tom sought a more reusable solu­tion; thus, MkDocs.

MkDocs is writ­ten in Python so you’ll need to install that as well as pip. Once installed you can cre­ate and start run­ning a new doc­u­ment project. New projects start with a sin­gle con­fig­u­ra­tion file, where all set­tings are optional, and a /docs direc­tory which con­tains the Markdown source files. From a clean demo MkDocs han­dles pre­sent­ing the docs in a nice, clean-looking design. Built-in is live reload­ing; so any­time you edit an under­ly­ing doc­u­ment the site will reload upon sav­ing. There’s no build process or deploy­ment that needs to happen.

The docs direc­tory han­dles all your doc­u­men­ta­tion source. While it requires an index.md file you can include images, other media, and any CSS or JavaScript to tweak the basic theme. Theme’s all change on the fly and don’t impact the doc­u­men­ta­tion con­tent. It takes just one line in the con­fig­u­ra­tion file to change the design.

You can also inter­link all the docs with reg­u­lar hyper­links within Markdown. You can also use rel­a­tive links, though, if you’re work­ing within your doc­u­men­ta­tion folder. You can also use ref­er­ences to tar­get a page or title any­where in the documentation.

To push your doc­u­men­ta­tion site live to a server you can run mkdocs build and MkDocs will cre­ate a sta­tic HTML site with your con­tent, theme, and all nec­es­sary resources. Since it’s sta­tic HTML you can deploy it on any server or even GitHub Pages. There’s some GitHub Pages inte­gra­tion baked in to MkDocs that lets you run one com­mand, gh-deploy, and let the soft­ware build a full GitHub Pages site for your project.

The 1.0 release for MkDocs is in-progress. You can help Tom make it hap­pen by con­tribut­ing on GitHub.

Write the Docs: David Hooker — What I have taught developers about writing

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.

David wrapped up day one of the con­fer­ence. He works as the writer at Prezi and han­dles the knowl­edge base, the engi­neer­ing blog, and pretty much any­thing you see with words and Prezi.

In some way, shape, or form com­mu­ni­ca­tion can let us down. A belief in doc­u­men­ta­tion is a belief that com­mu­ni­ca­tion can be improved through writ­ing. You’ve cre­ated some­thing you’re proud of and you want to share it with the world so that they use it.

The best way to engage someone’s inter­est is to hook on to emo­tion. Your words are what allow you to do that.

David out­lined 4 rules for draw­ing upon someone’s emotions:

  1. Start with the good shit. Don’t start with the back­story, start with what’s interesting.
  2. Keep it sim­ple. There’s lots of places where com­plex writ­ing can go wrong.
  3. Write what peo­ple actu­ally say. Usage trumps any of the rules; for­mal lan­guage rules are just that, formal.
  4. Don’t repeat. Repetition in speech sounds great, but the eye doesn’t like it.

You can choose to make your writ­ing excit­ing. No one needs to be able to tell that an engi­neer wrote your documentation.