Blog Archives

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

Working with an engineering team

Earlier this week I spoke at a Write the Docs meetup in San Francisco. The topic was “Working with Engineers”. Kael Oisinson, a support engineer at Atlassian, gave a talk too. It was great meeting him and all the Write the Docs SF folks.

This was my first ever Write the Docs meetup. What a warm, enthusiastic group of people! There were 50 to 60 attendees (see the meetup description and attendee list). Most were technical writers, with a scattering of software engineers and support engineers.

Kael Oisinson, a support engineer at Atlassian, gave an engaging speech about the life of a support engineer who discovers the value of creating documentation as a way of scaling access to information. It was really good to hear a point of view that’s related to, but not exactly the same as, a technical writer’s. We should do that more often.

My presentation is available on SlideShare: Working with an Engineering Team. Here’s an outline of what we discussed:

  • Sit with the team
  • Grok teamwork and audience
  • Play with the team
  • Adopt the team’s methodologies
  • Get to know the tools
  • Gather and share information

The group was lively and fun, with plenty of interaction and questions. Thanks to Tom Johnson, Laura Stewart, and the Write the Docs SF organisers, for a great evening.

Learnings from a doc sprint

A doc sprint is an event where technical writers work with engineers and other product team members to develop or update documentation. A well planned doc sprint is productive and rewarding for the documentation and the participants. This post shares some of the things I’ve learned from recent sprints.

A doc sprint can last anything from a few hours to a few days. I’ve found two days to be a useful period when the focus is fixing bugs. That may seem a little long, but it gives the disparate members of the team time to contribute to the sprint while keeping their primary roles ticking along too. When working with a distributed team across time zones, it’s particularly useful to have a flexible period that gives everyone the opportunity to take part.

Sometimes people use the term “doc fixit” when the sprint is focused on fixing bugs rather than developing documentation for a new product. Either way, a sprint or a fixit is a time box focused on the documentation.

Why run a doc sprint?

The primary goal is to fix documentation bugs and thus improve customers’ experience of the product. Sometimes it’s hard for a small team of technical writers to find the time to fix the small things. Yet, to our customers, those small doc bugs can mean death by a thousand cuts.

By inviting the developers and support or sales engineers to update the documentation, we make immediate and direct use of the expertise of our subject matter experts. By inviting product managers and programme managers to assess the documentation requests and help prioritise them before the sprint, we’re making use of their product and customer knowledge too.

Another goal is to foster a feeling of ownership of, pride in, and responsibility for the documentation amongst the engineers. It’s likely that they already know the value of the documentation, but they may not feel empowered to suggest and make updates. The hands-on experience of a doc sprint gives them that power. The feeling of power lasts long after the sprint has ended.

A doc sprint offers an opportunity for people to meet each other. Technical writers meet engineers and other members of the product team that we may not cross paths with often.

Some things I’ve learned from running doc sprints

These are a few things that have made an impression on me from recent sprints, and some hints that I’ve picked up along the way:

  • Engineers and other members of the product team appreciate the value of the documentation, and are keen to help improve it.
  • When deciding which tasks to allocate as suitable for the doc sprint, include some gnarly ones. It’s tempting, as a technical writer, to think that some tasks can be handled only by a technical writer. Well, that is true for some tasks :) but recently I’ve found it’s rewarding to err on the side of “let’s do it”. Big things happen in a doc sprint. Big bugs get squashed with surprisingly little fuss.
  • As the technical writer, be prepared to spend the entire period of the doc sprint reviewing changes, rather than making changes yourself. The main benefit of getting software engineers and support engineers to fix bugs is that you’re making direct use of their technical and business knowledge. They know the products and systems, and the ways the customers use them. On the other hand, the engineers don’t necessarily know the ins and outs of your documentation system. So, while the facts are probably right in the documentation created during the sprint, you’ll need to tweak the language and the adherence to other documentation standards like content re-use and page structure. It’s best to do that as part of the sprint, so the bugs can be closed off.
  • Create bug hot lists, to give people priority and focus. A hot list is a collection of bugs of a certain type. Since they’re fairly crucial to the success of a sprint, I’ve dedicated a separate section to hot lists below.
  • Hold a kickoff meeting at the start of the sprint, to give people information about what they’re doing and how to do it. Keep the kickoff short: 15 to 20 minutes is good. But allocate an hour, in case people have lots of questions.
  • Create a sprint guide that you can share with the sprint participants. The guide should be short and sweet, including information such as the date(s) of the sprint, the aims, the sprint organiser, the time of the kickoff meeting, the links to the bug hot lists, information on how to update the documentation, and where to send the reviews. Walk through the sprint guide at the kickoff meeting.
  • If you have the budget, provide food and prizes. For example, cakes at the kickoff, and prizes for most bugs fixed, most scary bug tackled, and so on.
  • Send out a report on how things are going at the end of the first day, as well as a wrapup after the sprint has ended. Include interesting bits of information such as who fixed the first bug, how many bugs have been fixed so far, and the scariest bug fixed.

More about hot lists

A hot list is a collection of bugs of a certain type. Many bug tracking systems offer a way of creating hot lists, naming them, and allocating bugs to them.

Hot lists are key to the success of a doc sprint where the focus is fixing bugs. When planning the sprint, I spend quite some time devising a set of hot lists that helps define the aims of the sprint, then filling the hot lists with issues. It’s worth it. When the day of the doc sprint dawns, people can get started immediately, even if I’m not there yet. (That last is particularly handy when my day starts five hours after many of the team members’ due to time zones.)

It’s fun to think up some attractive, appealing names for the hot lists. For example, being in Australia, we chose the name Mozzie (mosquito) for the hot list of small, easy fixes. For the big scary bugs, we chose Huntsman (a rather large, strangely beautiful, but admittedly scary, spider). In our most recent sprint, we created a hot list called Product Manager’s Choice (fix these bugs to win a PM’s mark of honour) and another called Technical Sales Engineer’s Choice (fix these bugs to win a TSE’s undying gratitude).

Note that a bug can appear in more than one hot list. For example, a big complex doc request could be a Huntsman as well as a Technical Sales Engineer’s Choice.

Have one master hot list for the sprint, which includes all bugs to be tackled during the sprint. This hot list will be invaluable in tallying up totals when the sprint is over. It’s also a good container for bugs that don’t fit into any of the other hot lists, but which you’d still like tackled during the sprint.

Having hot lists also makes it easier to award prizes based on the hot lists.

More about doc sprints

If you’d like to know more, try some earlier posts on planning and running a doc sprint. The sprints I’ve been involved in recently have focused on bug fixing. In earlier sprints we created entirely new documentation sets.

Bug husks

These are the husks of two cicadas that I spotted while walking in the bush. The bugs themselves have shed their skins and gone on to bigger, better things.

Cicada husks

Write the Docs San Francisco, January 2016

I’ll be speaking at Write the Docs San Francisco, on Tuesday, January 19th. The topic is “Working with an Engineering Team”. I’ll share some tips that I’ve picked up while working at Google and Atlassian, and open up the discussion for input from the attendees too. This is a great topic, and many people will have varied experiences and best practices to share.

The meetup is at the Splunk offices (250 Brannan St., San Francisco) at 6.30 pm on Tuesday, January 19th. For signup and more details, take a look at the Write the Docs Meetup.

Here’s an outline of my talk, Working with an Engineering Team:

  • Sit with the team
  • Grok teamwork and audience
  • Play with the team
  • Adopt the team’s methodologies
  • Get to know the tools
  • Gather and share information

This will be my first Write the Docs meetup. I’m delighted and excited to meet everyone!

How a developer accesses an API

This post is one in my emerging series of API basics from a technical writer’s point of view. How does a developer get hold of an API, so that she can use it in her application?

The other day, I was chatting to folks in our Marketing team about the three essential items of information an API quick-start guide should give developers:

  • Where to download the API and other tools you need.
  • Where to get your API key or other required app credentials.
  • A hello world app or some basic sample code.

During that discussion, I realised that the first item (“download the API”) differs depending on the type of API you’re discussing. It’s not always a case of downloading the API and adding it to your development project. Sometimes you don’t need to download anything – you just send a request. Sometimes the download happens each time your application needs to use the API. And sometimes you download something in your development environment and compile it into your application project.

Before the recent discussion, I’d understood the difference subconsciously, but during the conversation it became clear to me that this is something worth bringing to the fore, especially for those of us who need to document or market APIs. It’s a useful way of becoming more familiar with the types of API that we’re writing about. (If you’d like to know more about the various types of API, take a look at my attempt at a tech writer’s classification of APIs.)

Calling a REST API or other web service API

As a developer using a REST API or other web service API, you don’t necessarily need to download anything. You can simply start sending requests over HTTP and receiving responses from the API, which does all the work on the server (“server side”). In some cases, however, the API developer or the development community supplies client libraries that developers can download to provide the basis for their app’s interactions with the API. Examples are the Flickr client library for .NET, the Twilio client libraries, and the client libraries for the Google Maps web services.

Importing a library-based API

For a library-based API, you need to import a library of code or binary functions into your development project (your application). Then you can use the functions and objects in your code. When using a JavaScript API, for example, you get the API by including a <script> element in your HTML page. The <script> element loads the library supplied by the API. In this case, the download of the API happens every time the browser loads the HTML page. This type of API is sometimes referred to as “client side”, because it runs in the browser on the user’s computer. To see an example, take a look at the documentation for the Google Maps JavaScript API, which describes the <script> element needed to load the API library.

For an Android API, you install the Android SDK and then add any additional SDK packages into your development project, within your IDE. (An IDE is an integrated development environment, such as Eclipse or IntelliJ IDEA.) In this case, the API download happens when the developer builds their application. See the Android documentation on installing the SDK and additional packages. The Google Maps Android API, for example, is one of a number of APIs distributed via the Google Play Services SDK, which is one of the packages described in the above link.

Downloading a flower

Recently encountered in my neighbourhood: This sulphur-crested cockatoo is importing a flower recently downloaded from a bottlebrush tree. :)

How a developer accesses an API

Follow

Get every new post delivered to your Inbox.

Join 1,649 other followers

%d bloggers like this: