Tag: Write the Docs

Session notes from Write the Docs, a conference in Portland, OR and Budapest, Hungary about crafting great documentation.

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 second day of talks. He writes code and books. The latter is the story he told.

The publisher found him after Swizec wrote a short blog post about displaying dots through d3.js. About a month after the blog post he got a book proposal via India. That was October of 2012. He quickly read the spec for d3.js and faked his way through an outline. The “good” news was that the publisher liked the outline and signed a contract for the book.

Then came the writing of a book. He outlined 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, figure it out.
  3. Code it. Prove that you’ve actually learned something; it’s a means of testing your writing.
  4. Write about it. Pull it all together and synthesize the experience.

The nice thing is that writing about something you’ve already learned how to code can be extremely easy. Finishing the book becomes about repeating that cycle for each and every chapter.

After 66 days and 171 hours of writing 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 editing. While he was happy with the book the publisher came back with, “We love it!…but not really.” They wanted him to shorten the book by 60 pages. Swizec then rewrote everything. While he didn’t have to make new examples he essentially rewrote every piece. He killed the beautiful turns of phrase, jokes, and other pieces that made writing fun. Throughout the editing process he relied heavily upon On Writing Well.

That was the major rewrite. He then did another minor rewrite of additional typos and fixes. Unfortunately then the technical editors got back with their feedback and suggested even further rewrites to the technical examples in the book. Luckily by this point publication was so soon he refused to do deep structural changes. The book was published in October of 2013, one year after starting. After 12 months and 333 hours it somehow ended up being 194 pages long. It shipped on his birthday.

After publication he didn’t get much information, just a quarterly report of sales and royalties. It’s sold about 1,000 copies so far.

Overall Swizec learned that publishers are difficult to work with and that books can be the best way to learn a piece of software. Writing a book is a hard, humbling 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 concepts of agile software development and focused on how they can apply to writing. She works at Red Hat and lives in the Czech Republic. In a previous role she was a scrum master in an agile environment.

Mikey started her talk with a brief background or history of agile development. Traditionally software development relied upon a waterfall process. While this process worked well for physical factory production it didn’t work as well for digital software. All of a sudden we didn’t have time any more. The delivery time for software had to be faster and faster; users are impatient. The shift was toward more incremental, iterative development. This led to agile. Agile goes through the design, code, test, ship process multiple times rather than in one monolithic cycle. The key is to be flexible and adapt to whatever environment you work within. There are 4 key principles to agile development:

  1. Individuals and interactions over processes and tools. While there is value in processes and tools the people you work with come first.
  2. Working software over comprehensive documentation. Docs are still okay, though, you just want to ensure they’re granular and not monolithic.
  3. Customer collaboration over contract negotiation. As a writer you want to hear what the customer has to say and make docs a first class citizen in the software.
  4. Responding to change over following a plan. The key is to stay aware of what’s coming down the line and shipping every day in the code.

The flexibility in this is how agile relates to writing docs. As a writer you’re thrown in to an environment that you must adapt to. Staying ahead of the code helps ensure your docs never get swamped by current 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 conference happen, is an evangelist in the Drupal community. His talk focused on documentation in a post-agile world. Given the more hectic nature of agile software development ensuring that your documentation is up to date is quite difficult. You end up maintaining multiple versions of documents, sometimes writing docs for features which haven’t yet shipped or even been finished in code. You know the docs will fail at some point, the question is when.

The trick, though, is that developers already solved these complexities in the shift to agile development. On the software side developers have automated aspects of QA in order to speed up deployment. Kristof believes we can take that same mindset to docs. You can do this by either merging docs in to tests or embedding tests in to docs. Both are difficult.

In DITA documentation is broken up in to references, tasks, and concepts. References are written in code or extracted from from code. Common examples are documentation around API functions; these become easy to test. Tasks let you document automated execution in your project. Concepts let you address places where terminology may change between two versions of your code. Using embedded RDFa or a thesaurus extractor you could try and ensure your code and documentation agree.

Kristof also talked a bit about building the ultimate user guide to the internet. This stems from his project WalkHub. The concept is that online tools and sites often require us to absorb too much information. Luckily, though, there is a shortcut; it’s about cognitive load reduction. People have a limited amount of working memory and if you dump too much information 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 lightning talks. He works as a writer at Red Hat and focused on where community documentation meets product documentation. His talk explored whether a community could write your proper, official documentation.

As writers we never have enough time to pursue all the projects we want to accomplish. The community Fintan works with has written about 1,000 pages of the 6,000 total pages of documentation. While the community’s documentation lives in a Confluence Wiki the official Red Hat documentation needs to live in DocBook. The community wiki gives a low barrier to contributing an pairs instant publication with plain text editing. DocBook, on the other hand, is more complex to edit but presents good formats for archiving docs and has a rich markup vocabulary.

They rely upon a commercial tool to convert the Confluence wiki information to DocBook. Simply converting the content, though, isn’t enough. There’s still a distinction between community documentation and corporate documentation. What they run in to in this process is:

  • Variable quality in community docs. There might be different formatting, styles, or more.
  • Community documentation frequently has different versioning.
  • Community documentation may have inappropriate content, links, and more. Things like untested features you’re not yet supporting.

Given that, Red Hat goes through a process for synchronizing their community and product docs. They use a separate repository for each and maintain a series of snapshots for both sets. These are stored in their version control system. Ideally these sets stay close to each other. In reality, though, after a couple releases the two sets diverge quite a bit.

What they’ve done is simply compare the community docs with an automated diff tool and then merge those changes in to the current product docs. It trades a bit of manual labor for less divergent doc sets.

Ultimately bringing in community documentation from open source projects is tough, but worth it. The different formats, tone, and necessary information can take time to sort out but eventually 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 talking about blogging as non-traditional support docs. For WordPress.com the traditional documentation exists as a sprawling support site with hundreds of docs. The support staff primarily writes and maintains the docs.

Blogs help document things for readers in a few ways. First, they let readers subscribe and provide an incremental introduction to various topics. Email updates are occasional prompts to keep learning for new users.

Second, it turns documentation in to conversation. Readers can comment on the posts and interact directly with staff. That feedback loop can help guide future iterations.

Also, blogs have authors. Users know who the writer of a document is. It can help create an ongoing relationship between staff and users that’s based around creativity and proactive support rather than merely troubleshooting. That aspect can also expand the pool of people writing your docs. People have a better frame of reference for how to write a blog post than a support doc. At WordPress.com this means that the person launching a new feature or theme writes the initial support doc as well as the announcement post.

Blogs also give you a fresh start to your documentation. It’s easier to start a new blog than to overhaul an existing support site which means experimentation comes more easily. What you learn from blogging can then be applied to the documentation.

The two main ways this happens is through the main News Blog and through the Daily Post. The News Blog focuses on new feature announcements, company activity, and highlighting less popular or well known features. The Daily Post hosts weekly writing and photo challenges as well as focusing on more task-based instruction. In the last couple of months the Editorial Team has also put together a couple ebooks that focus on things like Photography 101. The material comes straight from blog posts over the months and acts as a great resource for new users.

An example Elizabeth highlighted was the Zero to Hero program started in January. Alongside each challenge there was an open forum thread for questions and comments. By the end of the month participants published 48 times as often as a randomly selected control 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, makers of Jira and other software tools for software developers. Their design team has grown from 5 to 30 over the last couple of years. On the whole Atlassian has focused a lot on the user experience of their products. Traditionally their tech writing has played a more formal or traditional role. They saw an opportunity to work together toward shared goals. Both are trying to reach users and give them a really great experience, they just use different tools.

A few of the design principles the docs team brought over to their work were to be familiar, to grow with users, and to give clarity to users. Those drive the decisions their design team makes. They realized those goals are easily adapted to documentation. Personas also play a role for both their design and docs team. The design team did a yearlong project to develop those personas. These make it easy for different teams to have common ground in how to build their software for their users.

The docs team realized in this process that designers have access to lots of customer information. They have interviews, site visits, usability tests, usage information on existing features, and a long-term roadmap for the product. All of that can help a docs team build documentation that’s relevant for users.

The documentation process for Atlassian starts in user testing. Designers test new prototypes with users and the docs team uses information from those tests to guide their documentation edits. They piggyback analytics on to this for hard data as well.

The first tool the docs team borrowed from the design team was empathy maps. Empathy maps help bring focus on the user. You can use them to workshop how a user might feel in a “before and after” situation. You take the “after” situation and work backward.

Another tool they’ve borrowed is sparring sessions. They’re basically a critique session that brings group thinking in to design and planning. It’s a check that the goals have been met with a given prototype. The goal is to assure design quality by critiquing design early and often. Prior to a sparring session they send out a draft of the doc as well as a brief or outline that covers the goals of a document. A few tips they’ve learned the hard way:

  • Timebox, timebox, timebox! Set a timer so you don’t go down rabbit holes.
  • If your team is given to negativity, try a positives-only 5 minutes.
  • Try to make sure everyone is heard. You can use a checklist or give everyone 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 workshopping tool they’ve borrowed. They drive focus on ideal solutions and get you out of “word-thinking” and can be a good way to build on each others’ ideas. Sometimes the best way to communicate an idea is to sketch it and really illustrate what a user will be seeing for a given feature.

User stores are an additional tool. It’s about figuring out how a user is going to go through a product. It charts a path through goals and actions within a product. Going through that path can help you spot where users will hit pain points and fall out of the flow.

They made all this happen by finding the right projects. They looked for a team that finds value in design and writing as well as a designer who sees the value in docs. It helps to look for a new project that’s running lean and has some momentum. Projects that are data-driven are also beneficial as it helps cement and validate 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 committer to the Apache project.

Apache CloudStack moved from an old documentation tool, Publican and DocBook, to Read the Docs. They wanted to bring in a greater sense of community with their documentation and make it more accessible.

The old tool, Publican, is a build tool for documentation written in the DocBook format. DocBook itself is a XML schema suited for books and papers; it’s not necessarily meant for web-based docs. The editing tools, though, are either technical like vi or expensive. For an open source project that’s a no-go. They were also running in to issues around localization, internationalization, hosting, and attracting new writers.

Using Read the Docs they were able to move toward using reStructuredText for writing. It’s an easy-to-read, WYSIWYG plain text markup syntax parser. The problem, though, is that they had 40,000 lines of XML to transform in to reStructuredText. Their lifesaver was pandoc. This let them convert all the files without needing to rewrite everything.

Sphinx allows them to build their documentation sites and projects. The hosting is handled through Read the Docs. One of the killer features for them was the button on each doc that let people edit on GitHub. Given that Apache CloudStack’s goal was to increase their contributor base this was vital. It dropped the barrier to entry for new contributors. They’re now starting to see drive-by contributions to docs, which is great.

The one last hurdle for them is translation. With large communities in China and Japan it’s key for the project to make translation easy. Handily, with Sphinx, they can do this. They use the same tool that Markus talked about yesterday. They now have more people contributing translations than they do documentation.

Ultimately changing documentation format gave Apache CloudStack docs which were good looking, easy to contribute to, supportive of localization, 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 learning material. We all suffer from ed-tech amnesia, in Robert’s words. There’s a huge body of research on how to teach people and how they learn material. In researching this talk he found that while there’s a huge body of material it is wildly arcane to us as technical people.

Robert works at the Open Tech School where they work to teach students programming. The workshops are done collaboratively with lots of hands-on coaching.

The first step in learning and collaborating is defining clear goals. You need to know where you want to go with the material; beginning with the end in mind helps greatly. There’s a difference between tutorials and references. References may seek to exhaustively document an API while tutorials consciously explain a single concept with an end goal defined.

Collaboration, though, can kill cohesion. With many people involved you have to actively protect the scope of learning material. At the Open Tech School they have someone who acts as the champion of learning documentation and they seek keep work tied closely to learning objectives.

When you use the right tools and lightweight markup you can lower the barrier to learning. For the Open Tech School this means using Jekyll and hosting files on GitHub Pages.

One thing that they haven’t found a good solution for is dealing with dependency hell. When teaching people how to code you run in to issues where the prerequisites for solving a given problem can involve setting up handfuls of other, irrelevant, dependencies. When teaching kids they’ve tried using system images that bundle those dependency requirements so students can write code and have it run right out of the box, mostly.

Another thing they have struggled with in their material is the amount of repetition. Repeating things is good, but at the same time you want to be concise so that students don’t skip over repeated material.

One guideline that is extremely useful for new coaches is to tell them the keyboard of students is made of lava. Too many new coaches cannot suppress the impulse to just fix one thing for the student. The problem is that this disrupts the student’s flow and attention. On top of that nudging new coaches to use socratic questioning can greatly help. Your students will benefit if you don’t just give them the answers.

At the Open Tech School they’ve found that feedback is great but that it’s mostly positive from students. Instead they focus on asking the coaches for feedback on where students struggle. It helps them spot the gaps and shortcomings in their documentation and learning material.

Finally, they’ve published all of their coaching guidelines.

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 software engineer at a web development startup in Brighton, UK.

MkDocs is a software project for producing nice-looking documentation from markdown files. Tom uses it with a lot of his own open source projects. Previously he handled documentation through Sphinx, which Markus talked about yesterday. This uses restructured text for documentation. Writing the actual docs, though, was not the most attractive process.

To help create more attractive docs with a clearer design Tom started drafting docs in Markdown. As he said, “The documentation is really the design of the product.” Using editors like Mou he was able to cleanly assemble and visualize his documentation. It helps to see what your readers will see.

From that experience he decided to tear up the existing tools and start again. Writing a custom little script he built the documentation for the django REST framework. The downside was that everything was hard-wired to this one project; it wasn’t the most reusable piece of code. Tom sought a more reusable solution; thus, MkDocs.

MkDocs is written in Python so you’ll need to install that as well as pip. Once installed you can create and start running a new document project. New projects start with a single configuration file, where all settings are optional, and a /docs directory which contains the Markdown source files. From a clean demo MkDocs handles presenting the docs in a nice, clean-looking design. Built-in is live reloading; so anytime you edit an underlying document the site will reload upon saving. There’s no build process or deployment that needs to happen.

The docs directory handles all your documentation 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 documentation content. It takes just one line in the configuration file to change the design.

You can also interlink all the docs with regular hyperlinks within Markdown. You can also use relative links, though, if you’re working within your documentation folder. You can also use references to target a page or title anywhere in the documentation.

To push your documentation site live to a server you can run mkdocs build and MkDocs will create a static HTML site with your content, theme, and all necessary resources. Since it’s static HTML you can deploy it on any server or even GitHub Pages. There’s some GitHub Pages integration baked in to MkDocs that lets you run one command, gh-deploy, and let the software build a full GitHub Pages site for your project.

The 1.0 release for MkDocs is in-progress. You can help Tom make it happen by contributing 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 conference. He works as the writer at Prezi and handles the knowledge base, the engineering blog, and pretty much anything you see with words and Prezi.

In some way, shape, or form communication can let us down. A belief in documentation is a belief that communication can be improved through writing. You’ve created something 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 interest is to hook on to emotion. Your words are what allow you to do that.

David outlined 4 rules for drawing upon someone’s emotions:

  1. Start with the good shit. Don’t start with the backstory, start with what’s interesting.
  2. Keep it simple. There’s lots of places where complex writing can go wrong.
  3. Write what people actually say. Usage trumps any of the rules; formal language 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 writing exciting. No one needs to be able to tell that an engineer wrote your documentation.