Blog Archives

Write the Docs NA 2016 wrapup

This week I attended Write the Docs NA 2016, which wrapped up a couple of hours ago. This post is a summary of impressions, with links to my notes on some of the sessions I attended.

One thing that strikes me about Write the Docs is that I’ve spent much of my time talking to people. This is partly because half of each day is devoted to unconference sessions as well as formal presentations. In the unconference sessions there’s a facilitator rather than a speaker, so everyone can contribute to the discussion. Another reason I’ve done so much talking to people is that there are so many interesting, friendly, enthusiastic people to talk to.

There were approximately 400 attendees. They’re people who love documentation – that is, people who know its value. Based on a show of hands at the introductory session, approximately 60% of the attendees are technical writers and about 15% are software developers. Others are UX specialists, support engineers, librarians, knowledge management specialists and more.

Another thing that strikes me is that the pre-conference activity was a half-day hike through the forested hills around Portland. Now, that’s my kind of activity.

The sessions

These are the notes I took from some of the sessions I attended:

For recordings of most of the talks, take a look at the Write the Docs 2016 YouTube channel. Here’s State of the Docs by Eric Holscher:

Doc sprints and API doc meetup

On the first day of Write the Docs, we gathered at Centrl Office to write docs and talk about API documentation. It was great chatting to so many enthusiastic, knowledgable writers. People got together and contributed to open source documentation with Mozilla, Google, and more. We filled three rooms to the brim. This photo shows the scene early in the day, before most people had arrived.

write-the-docs-writing-day

Conference venue

Days two and three were at the Crystal Ballroom. What a lovely venue! Here’s the view from the stage looking out across the conference attendees.

write-the-docs-ballroom

A closer view of the murals:

write-the-docs-murals

A chandelier:

write-the-docs-chandelier

More about Portland

My travelling bookmark, Mark Wordsworm, has some pictures and words about the city: Lost in Portland, Oregon.

Thanks

A huge thank you to the organisers of Write the Docs NA 2016. This is my first experience of a Write the Docs conference. I’ve wanted to attend for a couple of years, but it’s a long way from Sydney, Australia, to any of the conference venues. This year, everything came together and here I am. It was a great experience, and well worth the trip. Thanks!

A readable README file at Write the Docs NA 2016

This week I’m attending Write the Docs NA 2016. These are my notes on a session by Daniel Beck, titled “Write the readable README”. All credit goes to Daniel, any mistakes are my own.

Daniel Beck writes tech docs for developers and sys admins. A lot of his work is in deployment guides. In the course of his work, Daniel comes across many README files. In self defence, he decided to research README files, and looked at more than 200 of them. He analysed them from the following points of view:

  • The type of project the README documents
  • Other files accompanying the README file
  • The markup used in the README
  • The topics covered
  • Links to other files and documents
  • Images in the file: logos, other visual aspects
  • What was good and effective
  • What was bad or not helpful
  • How did the README make him feel?

Daniel found that README files vary in quality. Some of them are even hostile to the reader. Some of them miss vital information, such as project name or location of the project. Some READMEs are very old – the oldest one dates from 1974! Typically, they’re Markdown files that contain a lot of information in visually unappealing form.

Tools like GitHub and Bitbucket have brought README files back to life.

The best READMEs give you confidence about a project. They help the reader identify and evaluate the project. They help you get started (use the project at least once) and engage with the project.

So, README files are useful, and are something we’ll probably need to create. Daniel cautioned us against relying too heavily on templates for README files, as a template may make you think that you’ve included everything you need even though there are some gaps.

Instead, Daniel has prepared a README checklist, available on GitHub. It’s a useful document, in that it suggests parts you may need in your README file, and also describes what to put in each part, tips on how to find the content for that part, and guidance on when you may need the part. Daniel also pointed out the template for contributing guides for open source projects.

Thanks Daniel for an entertaining and instructive talk, and for a useful checklist!

API documentation tools at Write the Docs NA 2016

This week I’m attending Write the Docs NA 2016. Today is a kind of pre-conference day. There are doc sprints, and an API docs meetup.

At the moment, I’m in the API docs meetup. The day starts with a few set talks, to be followed by “open space” sessions. Here are my notes on the first couple of talks about documentation tools.

Docbox and retext-mapbox-standard, from Mapbox

The first talk of the day was “REST API documentation generator” by Rafa of Mapbox. The Mapbox team writes the documentation in Markdown. In the background is Jekyll and GitHub pages. Rafa walked us through a couple of pages of the documentation, which includes code samples, generated for various programming languages, as well as hand-written words.

Tools:

  • Docbox: An open source documentation tool for REST APIs. It’s a JavaScript application written in React (a JavaScript library for building user interfaces). It includes automated testing of the code samples in the docs. This looks like a pretty interesting collections of tools to explore.
  • retext-mapbox-standard: An open source tool that checks for grammatical consistency and correct spelling. This is implemented as tests, run against the documentation. It’s written in JavaScript.

Rafa said this set of tools works really well for collaboration on writing the docs.

There was a lively discussion at Rafa’s session, with a very engaged audience. We discussed topics such as reader feedback, automated testing, size of the doc set, versioning, and more.

All this information was packed into half an hour! Thanks Rafa for a great session.

Tight coupling of API docs: YAML and custom tooling

The next session was “API documentation tooling at Capital One” by jennifer rondeau. Jennifer talked about the options and challenges for tight coupling of API documentation. Creating docs manually is not optimal. To keep your docs up to date, you need automated ways to sync your docs with your code. That’s what Jennifer means by “tight coupling”. In this talk, she’s focusing on the reference documentation, and specifically REST API reference docs.

You need to automate,  but be ready for the areas where you need human intervention:

  • Prefer a design-first rather than a code-first approach to creating an API. Jennifer’s team uses Swagger. For the most part, they use Swagger for naming conventions and exposing usable external APIs, not so much for the architectural considerations. Jennifer gave an example: Assume your development team creates a parameter that currently has only one permitted value. The parameter exists to allow for future expansion. In the external docs, remove the parameter.
  • Note that Swagger YAML is human-readable, but not really. Jennifer emphasises that Swagger-UI is not a documentation tool. Swagger is most useful for generating server and client code. So, you need doc tooling. Jennifer’s team uses tooling that converts the Swagger YAML to a markup format (Markdown or HTML), and puts it all in a single file. Then there’s a manual step to clean up the text in the generated export files. You need to clean up the arrangement of the file, then expand descriptions and so on.

Jennifer walked us through the Capital One Platform documentation, and particularly the SwiftID webhooks, which is the output of the above processes. The hello world content is manually created. The source is all AsciiDoc, either generated from the YAML or hand-written. A member of the audience commented that it was good to see the manually-written content integrated with the generated docs.

Next, Jennifer discussed a different approach: creating documentation from tests. Jennifer talked about spring-restdocs, which adds the stubs for the documentation. You can then go and add the text later. How you automate your docs depends on how you’re building your API. The docs-from tests approach is useful particularly if you use the code first approach to creating an API. Your docs must exist in order for your tests to pass.

Thanks so much, Jennifer, for these tips on how to Swagger, and the hint about sprint-restdocs.

Webinar on API technical writing with STC India

Are you interested in learning about APIs and API technical writing? Join us for a webinar, hosted by STC India. I’ll demo a couple of APIs and discuss the role of a technical writer in this area of the software industry. We’ll look at examples of API documentation, and discuss what type of documents an app developer expects when using an API.

The title of the webinar is “Introduction to API Technical Writing”. It’s intended for technical writers who know little about APIs (application programming interfaces) and want to explore the field of API technical writing. My hope is that, after attending this webinar, you’ll have the knowledge and tools you need to head off on your own explorations.

APIs (application programming interfaces) make it possible for applications to share information with each other. You could say that APIs are the communication channel of the online world. Developers need help hooking their application up to someone else’s APIs. We, as technical writers, give them that help.

Recording of the webinar [Update on 10 April 2016]: The recording of the webinar is now available on YouTube: Introduction to API Technical Writing.

Registration details: Sign up for the webinar, and read more about it on the STC India site.

Date and time: Friday 18 March 2016, at 1pm Indian time – that’s 6.30pm in Sydney. The session lasts one hour.

Who can join? Anyone. It’s free of charge, and you don’t need to be a member of the STC.

Topic overview:

  • An introduction to APIs.
  • An overview of the role of API technical writer.
  • Our audience – the developers who need our documentation to use APIs in their applications.
  • The types of API we might be asked to document.
  • Demos of 2 APIs that you can play with yourself.
  • What API documentation consists of.
  • Examples of good and popular API documentation.
  • Working with engineers.
  • Tips on getting started as an API technical writer.

Hope to “see” you at the webinar.:)

Git-based technical writing workflow – notes from a TC Camp session

This week I attended TC Camp 2016 in Santa Clara. In the morning there were a few workshops, one of which was titled “Git-based Technical Communication Workflows”. A team from GitHub walked us through a workflow using Git and GitHub for technical documentation. These are my notes from the session. Any inaccuracy is my mistake, not that of the presenters.

The session covered primarily workflow on GitHub.com, and also touched on using Git on the command line. There was a good variety of Git skill levels amongst the attendees, from people who had never used Git or GitHub, to people who were comfortable using Git on the command line.

The presenters were Jamie Strusz and Jenn Leaver, both from GitHub. Stefan Stölzle was there as technical advisor, and answered plenty of questions from attendees.

Jamie started with an overview of the  traditional GitHub workflow. Then Jenn, a technical writer at GitHub, explained her workflow for technical writing in particular. Here’s the repository that they created during the session, to illustrate the workflow: TCCamp demo repo on GitHub.

Some things I gleaned about a technical writing workflow using Git and GitHub:

  • When a fix or update is required to the documentation, the technical writers start by raising an issue in the help docs repo.
  • Next, the technical writer creates a branch.
  • Jenn’s team occasionally uses “mega branches” used by several technical writers working on a feature. But usually, Jenn just works in her own branch.
  • The term “mega branch” isn’t generally known. I suggested that it’d be great to have some information in the GitHub docs about best practices for managing such a branch. Jenn liked that idea.
  • Jenn’s team uses the Atom text editor.
  • The source format for the documentation is Markdown.
  • A useful tool for converting documentation from HTML to Markdown: pandoc.
  • A question came from the floor about Asciidoc. A few people have heard of it, and Jenn’s team is talking about it too.
  • They make all the changes in the branch, and make commits often.
  • They commit changes locally, then push to the web (that is, sync to the repo on GitHub). Then they make their pull request on the web.
  • Jenn likes to make pull requests (PRs) often, so that she can get feedback quickly. Sometimes she’ll have a PR with 200 changes in it.
  • More about mega branches:
    • Often the mega branch is for development of a doc change over a longer period of time.
    • Create a mega branch, then create branches off that mega branch.
    • Then you create the pull requests off your branch, and do the reviews there.
    • Then eventually push to the mega branch.
  • Jenn does not ever work off the master branch. The team of presenters recommend against working off master, because it’s more difficult to back out changes. GitHub views the master branch as the deployable state – so, it’s production. Therefore, always make changes and do collaboration on a branch. Then merge back into the master branch when ready for pushing to production.
  • A tip: sync with the main repo on GitHub often. In particular, before starting a new branch. Otherwise you’ll have problems later when merging your changes back.
  • Branches can be very small (just fixing a typo, for example) or very large (for a new feature).
  • It’s a good idea to be very descriptive with your commit messages, so that you can figure out which commit to roll back if necessary.
  • For version control within the files, Jenn’s team uses Liquid syntax. They also use Liquid for other conditional publishing, such as selecting enterprise docs only.
  • Git LFS (Large File Storage) is available for uploading large files such as videos, Adobe files, etc. For some of those files, depending on file type, LFS can also help you see the difference between versions. LFS also helps ensure that the large files don’t clutter up your repo.
  • What about conflicts, with multiple people working on the same doc? There are several ways of handling such merge conflicts. Some people use diff tools. Others rely on the comments that Git adds to the files about the conflicts: open the file in an editor, assess the conflicts, and make a decision about which change to accept.
  • Merge conflicts are reasonably rare. They usually happen if someone forgets to sync (“pull”) before starting a branch. Another time when it may happen is if you start working on something, and then the work gets put on hold for a while. When you start up again on that project, you may have conflicts.
  • What to put in a README file on GitHub: A general overview of what’s in the repo, and any vital information such as contributor guidelines.
  • Labels are useful for things like indicating status, such as “ready for review” or “in progress”, or something to indicate the feature under development.
  • The team uses the GitHub issue tracker as a primary communication tool. Even for things like noting when a team member is out of office, or for ordering office items. These issues go into the relevant repo. For example, at GitHub the team orders office items by creating issues in a “Gear” repo (which isn’t available for public viewing).
  • The commands that Jenn uses most often in her technical writing workflow are: git branch, git checkout, git status, git push, git push.
  • All reviews take place in a pull request. The team starts with a comment to start the conversation. They @mention people to bring them into the review, such as the subject matter experts. Before pushing the change to master, someone has to approve, by adding a squirrel emoji.:)
  • The team uses emojis all over the place in reviews! They use them in place of words.

Jamie created a repository which Jenn used to walk through each stage of the workflow:

  • TCCamp demo repo on GitHub.
  • An issue within the repo’s issue tracker: WIP – Jenn’s doc.
  • A commit.
  • diff shows the changes to a file or files.
  • A pull request. People who are watching the repository will get a notification of the pull request. To request a review by specific colleagues, use an @mention in the comments.
  • If you want someone to focus on a specific area, give them the URL of the relevant commit within the pull request.
  • You can leave a comment on a specific line within the code, as well as comments on the pull request as a whole.

Titbits:

  • GitHub uses an icon of a squirrel (an emoji, :squirrel:) to indicate when reviewers are happy for a change to be shipped. In some forms the squirrel has a name: Heidi. The presenters didn’t know why GitHub uses a squirrel. Does anyone know?
  • We were given a limited-edition GitHub Technical Writer Octocat sticker!

GitHub Technical Writer Octocat

Follow

Get every new post delivered to your Inbox.

Join 1,706 other followers

%d bloggers like this: