Featured techpubs tools

Introducing Docs Like Code

I recently tweeted about a side project called Docs Like Code and wanted to tell you about it here. It’s a specifically-focused site where I can share my best practices and lessons learned about applying software dev techniques and tools to software documentation. I want to learn and teach at the same time as I keep exploring this space.

If you want to see a bit of how the site is put together, and how you can use GitHub to make web sites, join in. I have an email list you can join to get information as the site grows.

In the meantime, take a look at this quick less-than-five-minute look at how you can build Jekyll sites locally.

API techpubs writing

Modernizing technical documentation

As a technical leader at Rackspace during a docs modernization effort, I want to respond to Tom Johnson’s recent pointer to the developer docs site as an example of treating docs like code. Not just specifically for the “will it scale” questions, but for the questions I have fielded and continue to answer. Believe me, “Will it scale?” is the least of your concerns in a complex overhaul of attitudes, processes, tooling, and expectation setting.

I’m sure modern docs are not going to work for all projects and all people and all processes, but since I have first hand experience I thought it would be helpful to talk about it.

In case it helps, let’s describe the disruptions at the heart of the movement. You can see that outcomes matter.

Web delivery

If your old tooling cannot provide a great web experience, you need modernization. Traditional tech pubs tooling (Adobe, Madcap, Docbook) will struggle to develop wonderful, responsive websites that provide an amazing experience with documentation. There’s a natural struggle between artisanal hand-crafted documentation and producing tens of thousands of web pages that still offer a great experience despite the size of the site.

Continuous integration for documentation

When you treat docs like code, expect to enable more contributors, and when you enable more contributors, you need to automate builds and quality checks so your time is spent focused on doc outcomes, not running builds. Let the robots take care of builds and use tools that don’t require a seat license so that the writers aren’t having to build from their computers only. In OpenStack we can merge 50 changes a day in a single repository containing ten deliverables (web-delivered guides). We build draft copies with scripts for people to review the output online.

If traditional tech pubs tools product managers are reading, your next killer feature is Travis-ci job integration, Jenkins job enablement, and really any scripted way to build your output so that humans don’t have to click anything to build the docs.


Collaboration for documentation using code systems

Depending on your contributor base, you influence more people to respect the documentation and encourage contributors to improve the docs with you when the docs are in a code system. Across multiple repositories we deliver REST API documentation for almost 30 services. Some days there are over 100 changes that need to be reviewed for REST API docs.

Content management using code systems

I’ve presented and written about using code systems for documentation – git, GitHub, BitBucket, GitLab, and so on. See the resources section for a deep dive, but suffice it to say, I’m sold on using GitHub for your CMS and I know many other writers see it this way also.

Valid concerns

Here’s what you need to look out for and even embrace when the time comes:

Content sprawl: What goes where is a common question from contributors. Be ready with answers so your site doesn’t become a poor web experience. Have excellent navigation systems and way finders for readers.

Quality diminishing: Build a trusted set of reviewers and make sure they are equipped with a style guide and plenty of quality checks to keep in mind while reviewing. Be mindful and use metrics to ensure quality is a priority.

Loss of control: By enabling many contributors, you lose control of who writes what where. Be ready to trade control for many other benefits. I don’t have a control-based mindset so it’s natural for me to give up control in order to gain better outcomes.

Loss of choosing priorities: When you don’t personally manage and direct the teams of contributors, you don’t get to pick what is written first, second, or third. Or even if something is written at all. Have processes and systems in place for triaging doc issues, and create a culture where contributors have good judgement about what to work on first, second, and third.

Search and replace: When you need to make changes across multiple repositories and deliverables, be ready to up your bash scripting game or get help with it. Fortunately text manipulation is pretty powerful at the command line. Unfortunately some teams could be stuck with non-Linux-based systems and no tools to help with this problem.

Naming agreement: Unless you establish standards and have authority for naming certain parts of a project (plugin or plug-in as an example), you could waste time arguing about which name lands in the base.

Value diminishing: If you can’t train your writers to stop nitpicking grammar errors or capitalization consistency issues, and instead do technical reviews, you might have problems with a docs-like-code approach. In a docs-like-code world, be sure you know what is the most valuable contribution and make sure your teams can give those types of contributions.

In closing, you can see I’m a huge advocate for this approach to documentation. Please take a look at the resources I’ve been working on over the last few years to spread my enthusiasm and excitement for the modernization of technical documentation.


First seven jobs with stories

Babysitter 👶

My first job was babysitting. I distinctly remember going to one of my first babysitter jobs. I had to be about 13 years old, and it was for a newborn baby who slept the whole time. I basically watched TV the whole time. She wrote me a check and drove me home.When I got home and looked at the check, I realized it was for $20.00, which was much more than I had thought the job paid! My mom said it was fine to keep it but called the parents to be sure they meant to pay that much, and sure enough, she was so grateful for a night out she felt super generous in that check-writing moment.

Field worker 🌽

My second job was corn detasseling, walking corn rows and pulling tassels off corn stalks. I grew up in northern Indiana, and they paid kids as young as 14 to walk the corn rows and remove the tassel at the top of certain rows so that the hybridization would be completed for the type of hybrid corn they want to grow in that field. It was hot, dirty, and way more boys than girls would do this job. It paid well, I wanted to quit after a week, and I rode with a neighbor who was 16 at dawn-thirty every morning, taking a bus after that to the corn fields, packing a lunch each day.

Retail clerk 👟

My third job was selling sporting goods in a retail sports store, locally owned, as a retail sales clerk. I stocked shelves and racks, got shoes for people based on size, laced the shoes, and answered questions. I was their night shift, closer, and I was nearly fired after my first three nights because the cash register count kept coming up about $15 short. The day shift person was expressing growing concern as she came in to an inaccurate value each morning, so the owner came in at 9:00 one night to watch me count the cash drawer at the end of the night. He immediately asked my why I didn’t count the rolled coins. I had no idea I was supposed to! The confusion was resolved and I got to keep the job.

Parts inspector 🔎

My fourth job was inspecting manufactured rubber parts in a local factory, on the night shift during the summer in high school. We worked from night until dawn, hand-inspecting rubber o-rings and specially-made parts to make sure they did not have holes, tears, or other defects. It was smelly, (hot rubber manufacturing smell) dirty, (imagine black rubber dust under your fingernails and in your skin) hot, (though not as hot as the day shift), and loud. During the school year, one of our co-workers drove an elementary school bus after getting done with her night shift. She was famous for once saving the lives of a family when their house was burning and she noticed it from her bus-driver seat, ran into the house, woke them up, and got them to safety.

Library worker 📚

My fifth job was after starting college, checking out and shelving books at the university library. I wanted to focus on school and not work in college, but learned on a call with my Dad late one night the first week of school that I would have to work to cover costs or come home. I was lucky to land one of the work/study jobs as a desk clerk and book shelver in the four-story library on campus. I could walk to work, I could read and study when it was not busy, and I helped shut down the entire library at night. I remember turning out all the lights on the basement floor, then walking through the pitch black to the elevator, finding the button on the wall, and waiting in complete darkness for the narrow crack of light to appear to take me out of pure darkness. Once someone called in to the library to ask if she could retrieve a $100 bill she left on one of our copiers. Asking her to hold, I went downstairs, opened the lid of the copy machine, and sure enough, there was a $100 US dollar bill. I picked it up, picked up the phone, and told her she could come in to get it. That was one relieved voice on the other end of the line.

Chemistry lab worker (internship) 🍼

My sixth job was inspecting baby formula and drink supplement ingredients as an internship in a chemistry lab. This was another shift job, this time on the second shift from 2:00 in the afternoon until 10 pm. I drove across the Michigan/Indiana state line for this job. I had to wear steel-toed shoes and a lab coat. I remember using my thumb to pipette some liquid, where you have to release some air to get the liquid to the right level for a precise measurement. When my trainer saw me, he immediately re-trained me, showing how to hold a pipette properly using an index finger for more control and finesse.

Word processor (assistantship) 📏

My seventh job was assembling, word-processing and testing science education materials (such as Chemistry with TOYS, Physics with TOYS) as a graduate student. I also made copies, worked on NSF proposals, and assembled small science kits as giveaways at science educator conventions. One task was to staple more than 400 small cellophane fish to quarter-page instructions on teaching physical science with the small fish. After completing those and boxing them up neatly, I traveled to a science convention, met my boss there, who asked where the 400 fish kits were. They were still on my desk! I hadn’t realized that the assembly of the kits was FOR the conference I was attending. They had to call and have the fish boxed and shipped. I still think of that incident when I don’t have the big picture for a smaller task. Did not get fired then either, thankfully.

community tools

Reflecting and making: Inspiration in Ann Arbor this summer

I’ve written up my experiences at a leadership training class for OpenStack in Ann Arbor this summer. You can read more on the OpenStack blog.

We also had the opportunity to tour a maker space close to the training center, Ann Arbor’s Maker Space, and wow, it is neat. Comparable to a monthly gym membership model, they provide large woodworking and metalworking and industrial sewing and crafting machines for a daily or monthly fees or full memberships. Staff members are available for training, and each station comes with documentation. You can store large and small projects in progress so you don’t have to lug your work back and forth.

Tom Root, a Miami University graduate like me, started the space during the financial crisis in 2008. He has a vision of uniting a community of young people who need and want vocational and trade education with the experienced workers in the community who may have lost their traditional manufacturing jobs but have a lot of knowledge and experience to pass on. The Midwesterner in me knows that this type of collaborative space makes so much sense.

I was so inspired by the woodworking shop I decided to come home, buy some mesquite wood, and mimic some window treatments I’d seen on Fixer Upper for my own living room.



Here are some photos from our tour of the 11,000 square foot Ann Arbor Maker Space.

IMG_0972 IMG_0971 IMG_0978 IMG_0976

community techpubs work writing

Influencing community documentation contributions

After a week with leaders in the OpenStack community, taking leadership training, I’m inspired to write up ideas from Influencer: The New Science of Leading Change. For me, who needs to make the most out of community efforts, the idea that no one likes being told what to do was a familiar phrase. Rather, compel people to pick up your vision and add to it.

As an example, people often ask me, how do you motivate people to write documentation for open source projects? Or write for any software project?


Get details about the behavior you want to see

Using the framework this book offers, you first want to identify the behavior you want to see. Their examples often revolve around healthcare, such as hand washing. But you can get very specific about hand washing, such as where, when, and how. For documentation, you may say the behavior is “write” but I want to get more specific than that. Where should they write? Is the behavior “write a personal blog post?” Or is it “write in the official docs?”

Also, when should they write? Ideally as close to when the technical detail is still fresh as possible. The “when” could be at the end of a cycle when people are less distracted by feature additions. Or write documentation before the code is written and revise it often.

As for “how” do we want contributors to write, well, we may need to have templates and frameworks for the “how” — such as source formats, build jobs, and in which repo.

Looking at the behavior we want to see, getting super detailed about it, we find that we also want to encourage the behavior of code reviewers to read and review related docs.

Identify a crucial moment

Now, when a bit of code changes that makes a difference in the docs, that’s a crucial moment for influencing a particular behavior. The behavior we want to see is writing documentation while the code is fresh in your mind.CC Jonathan Cohen

Another crucial moment to engage is when a user first tries the feature; their fresh eyes may provide an update to the docs that others might not see. The “Edit on GitHub” feature of creating a pull request provides that outlet for fresh eyes to make a quick edit to the documentation.

So we have an idea of the behaviors we want to see, and a sense of when we want to see them. Now we can begin to ask what’s preventing the behavior.

Why don’t people contribute?

Let’s talk about: what’s painful about writing documentation? For example, if you speak English as a second language, it may be painful to write for others to review and the criticism might be more than you can bear. Kind, empathetic coaching, respect, and a culture of acceptance helps with this barrier.

Provide guidance and energy

Also, people associate boredom with docs. They look at a blank screen and can’t come up with words to describe their feature. They yawn and check their Twitter feed instead of writing docs. This pain point is where templates can help. People who don’t know what to write might need guidance, suggestions, or strict form-based templates.

Avoid context switches

It’s painful to have a doc tool set that’s extremely different from what you write code in — the context switch even to a web-based editor may be too big a barrier to jump over. Make the docs like code whenever you need to compel developers to write.

Get some influencers who believe in the vision

Without actual peer pressure that says “yes, we write the docs” developers may not create a culture that requires documentation. Start with the influencers in their peer group (which might not be you). For example, when a seed researcher wants to introduce a new hybrid seed corn, he goes straight to the local diner where the most experienced and influential farmer gets breakfast on Saturdays. It’s better to have the farmer in his pickup truck understand and believe in the benefit of changing to a new hybrid seed corn than for the researcher in his late-model Volvo.

Offer deliberate practice sessions

Also consider “deliberate practice” where you set aside time to get better at a skill. If the skill is writing, then have office hours or coaching sessions online, and at conferences make sure you can meet with people who want to become better writers to show them how to practice writing through drills, exercises, and with fun collaborative efforts such as doc sprints. Record a video or host an online hangout, showing all the steps for contributing deliberately and strategically.

Thanks to many coworkers who helped me discuss and think more about these ideas along the way. What are some additional ways to influence a desired outcome?


The journey is the reward

cc-by-2.0I’m re-reading Playing Big: Find Your Voice, Your Mission, Your Message by Tara Mohr. I’m at a certain transition point in my career journey which is taking me to a new role, a new team, and a new company. Reading Playing Big gives me a new framework, separate from Lean In, to think about how women shape careers and journey through life. And my journey has been and continues to be a great one: after a lot of consideration, I’m taking a compelling new opportunity at Cisco.

Rackspace has been a wonderful home for over five years, and I want to dive even deeper into developer experience: developer tools, outreach, and support (including docs, naturally). I want to study developer workloads for OpenStack infrastructure. I’m super excited for the amount of learning I can do at Cisco by joining their cloud group. I’ll still be working on OpenStack upstream and looking for ways to apply what I learn.

I write about it here so you can observe the transition not just on LinkedIn or Twitter, but also as a transition from tech writer to something new. I have a compelling journey to define.


Interface means integrate

I attended the Austin Homegrown API meet up at Wright Bros and Brew last week. Titled “Where the Rubber meets the Road,”—heh—there were about 25-30 people there, about half API-oriented and half car-oriented. Honestly, with interfaces and integration as a theme, all attendees were API-oriented. One of the people there simply to network had lunch with Lanham Napier (former Rackspace CEO) that very day, pitching his startup, though he never said what it was. Must be stealth time for his startup. Felt like quite the Austin moment.

carserv-logoThe format was two talks, the first was from a startup in Austin, CarServ. He showed their early findings when using the Edmunds Vehicle API to write an application that small maintenance shops can use to find out what maintenance any car needs. Their REST API contains a lot of data and this startup wants to make that easily available to non-dealership service providers. It’s a Ruby app. Edmunds provides a registered trademark “True Cost to Own” and “True Market Value” and I think someone should build a calculator for “True Time to Sell” based on service recommendations. (Someone do this!) The developer said they’ve had great response from Edmunds any time they’ve asked for increased rate limits.

The second talk was an API mashup with the Uber API and Google Calendar API “to make sure I’m never late again.” This was with Keith Casey about his proof of concept and it was fantastic, because it’s meant to be more thought-provoking than code-complete. I especially appreciated that he’s not exactly a fan of Uber’s business practices. The blog post at http://caseysoftware.com/blog/future-transportation-today has more info, and the code is here: https://github.com/caseysoftware/uber-project. He already got contacted by a product manager at Uber but doesn’t plan to work further on the idea. To me, the city planning discussions are as interesting as the mashup itself.

I was one of three women there, I believe, and there were three lawyers, one of whom was a woman, so there was a interesting mix. I think they were interested in the Edmunds data API legalities with data re-use. For sure there were job seekers there. Did you know that actual car designs have 450,000 requirements that have to be tracked? Yipes, that’s a whole other level of complexity in design.

All in all, a thought-provoking meet up with a great mix of technologists who think like entrepreneurs. Integrate, innovate, interface, repeat. The next Austin API meet up is April 6th at Capital Factory.

API work writing

Playing with technology

One of the greatest parts of my job is getting to learn, write, learn write in a never-ending pattern. I got to play with Docker Swarm on our Carina offering at Rackspace and wrote up this blog post. It’s a tutorial for using Carina to create a Jawbone App with node.js. You can see the results at https://sleepify.me.



While looking for a data-driven REST API for that tutorial I came across Mashape, which has a marketplace for APIs. I found the “They Said So” quotes API while looking around for a word-nerdy data project next. I could also try out the Merriam-Webster Dictionary API and of course, the best word-nerd API there is, Wordnik. So much data, so little time.

I find it fascinating that these API marketplaces are popular. Mostly when I ask developers about the usefulness of a site like Mashape they can’t come up with a great use case. I wonder if discoverability of APIs is an important part of promoting and educating people about your API. I think that with more and more API definitions, there is more and more need for discoverability. And of course, documentation. Opportunity abounds.

Why use GitHub as a Content Management System?

GitHub is a website that gives a user interface to source control. The tagline on the site is “Social Coding,” and I find that phrase to be an excellent summary of why GitHub is so useful for collaborative documentation. When writing for developers, write with developers, and believe me, developers are using GitHub for writing and coding. Like many tools, git and GitHub were created by fire—through a pressing need in 2005 for high-throughput and efficient source control management for the Linux kernel.

GitHub is the web interface, and git is the command-line tool that you use to copy files locally and track them. It’s cross-platform, so it works on Windows, Mac, and Linux operating systems. The biggest difference between git and other source control systems is that it merges files with a best guess rather than a “lock and checkout” model. The best guess for merging is often accurate but does require human inspection when the changes are too close to tell. The non-linear branching model means that you can experiment with many changes but still get back to a known state.

Here’s a brief vocabulary list for GitHub.

  • A repository is a collection of stored code or source documentation. For example, openstack-manuals.
  • A branch is an indicator of divergence from base. For example, the stable/liberty branch of openstack-manuals.
  • A commit is a point-in-time snapshot of a repository with changes. For example, this typo commit.
  • A fork is both an action and an object: forking is when you copy a repository, and a fork is a copy of a repository.
  • An issue in GitHub is a way to report defects, tasks, or feature requests. For example, an install article issue.
  • An organization in GitHub is a collection of repositories. For example, Rackerlabs contains Rackspace repos.
  • A pull request is a comparison of edits to see if the reviewing team wants to accept those changes into the main repository. For example, this pull request for a Rackspace page on developer.rackspace.com.

GitHub has some offerings that cover a couple of different use cases. Private repositories on the public site are about $7/month as a subscription and let you mark a repository as private and only invite trusted collaborators. GitHub also has an enterprise offering where the entire website is hosted where you want it and branded with your domain name. With GitHub Enterprise, you can ensure only company employees can access the source and collaborate with each other. Look up more options and pricing information on https://github.com/pricing.

Why use GitHub instead of a traditional CMS for docs?

When you are collaborating with technical people on distributed projects, often they are already accustomed to a GitHub workflow. So applying that workflow to technical documentation related to the project is a natural fit. Also, since GitHub has flexible review processes and prioritizes continuous integration, applying those benefits to documentation reviews and builds gives you the benefit of content management while bridging to sharing knowledge with subject matter experts. GitHub is a great match for when developers are writing documentation in source control. GitHub works well when a project is so large or distributed that no one person can know enough to write the documentation for the project. While GitHub is often associated with source control, the collaborative aspects go well beyond the traditional source control and CMS models.

In OpenStack, we have documentation workflows that mimic our code collaboration. We post patches for people to review, we review each other’s patches (similar to a pull request on GitHub), and we have build and test automation for every doc patch. The idea is to use the collaboration available in the GitHub pull request workflow for docs as well as code. We’re all responsible for relevant and accurate documentation for about 25 OpenStack projects written in Python across 130 git repositories, so let’s work together.

I do get questions from writers who are getting started with these types of workflows, so I wanted to bring together some of the best practices we’ve found, and find more. Here are two articles that serve the purpose along with a slide deck from a presentation I gave this year.

community work

Google I/O 2015, Looking Back and Forward

I wore my Google I/O t-shirt the other day while hiking, and realized I hadn’t posted a write up from that developer conference back in May 2015. This year they had a big push towards bringing women to the conference through effective methods.

Google has an Android developer community called Women Techmakers, led by Natalie Villabos. She did an amazing job with the event itself, but what most impressed me was the building of community prior to the event through the use of Slack, emailed communications, and networking opportunities both online and in person. Natalie said they went from 10% female attendees in 2013 to 23% this year. The first night I went to a Women Techmakers dinner was at an amazing Peruvian restaurant. The giveaways were lovely zippered canvas bags with Adafruit’s Gemma wearables package for hacking on later, which is awesome. I got the system working the other night, and ordered an additional soft potentiometer hoodie pull so I can make this project with the hoodie I bought at the conference.

Gemma kit

This article offers a good overview of what they did to get more women to I/O. Here’s a short list:

  • Grants
  • Hackathons
  • Nominations from Googlers
  • Reserved invites to women coding groups
  • Dinners together
  • Network enablement such as a Slack channel before and after the event

I sat with three women at dinner: one is an engineer at Quora in SF, about a year out of college, the other was a product manager at Fox News in New York City for their app work, and the third I spoke to most is a developer at GreatSchools.net.

Faves and Raves

On Tap Now demo — or, how to not lose 20 minutes to your phone — was an example of a truly amazing context search. First, it brings us back to why we love Google in the first place. Second, she had a Skrillex song up and said, “OK Google, what’s his name.” I kid you not, I audibly gasped when it “just worked” and said “His name is John Moore.”

Expeditions gives Cardboard/VR to kids in classrooms. I went to this demo and it was pretty cool, we all sat on 360-degree swivel stools and turned to see what the “teacher” pointed us to in the VR screens. It was like having a fancy view finder. We went to Versailles in France, which I had very recently visited. It was impressive, but one aspect that threw me off was the cameras must have been super high off the ground. The Hall of Mirrors felt like I was floating through it rather than walking through it. But wow, what a cool experience for a classroom of kids. My second grader absolutely LOVED this.

Jump gives 16 cameras to do VR recording (Go Pro made one), Google assembler then makes it so you can interpolate the viewpoints and get 3 dimensions (depth-corrected stereo). gopro jump
I just read an article that said YouTube supports Cardboard for its videos now, here’s the help page.

Developer advocacy observations

Half the dev sessions were in these “alcoves” which were rooms created with cardboard tubes and boxes. It made for difficult hearing the presenter, even with mics on. Basically, no one left their comfy seating, so it was extremely hard to go around to different sessions.
cardboard alcove

I went to a Firebase demo, which had a great example of a developer advocate trying to identify with audience and do story telling. They did an example app that’s a chat application in a web browser that the audience could interact with right there. He could also turn the example chat off quickly if the crowd got out of hand in playing with it live. Side-by-side display made for a great demo as the noSQL updated before our very eyes.

Women at conferences, what’s in store?

As I reflect back on what it was like to go to a large tech conference with at least twice as many women as any I’d been to, I felt like the proof in the techniques to get us there is going to be in the return rate and the new signup rate. Will women feel like it was “their” conference too? Will they be annoyed with the overcrowding and not feel like it’s worth the extra effort to get on a plane? Will women keep returning because they’re there with their friends and it’s a tradition? Will women be more likely to spread the word about the conference itself to a wider group than just developers? I heard a woman explaining Google I/O to a man on the BART transit back to the airport, and thought, I haven’t seen much of that type of evangelism to the general public before. I think it’s going to take a while to see the effects of the special outreach efforts. I definitely think the diversity in networking effect is going to make a lasting change in the system. I sure hope so.


Lastly, I give you a great tweet from the guy in the hat in this picture said it with tongue in cheek, “14.2% men in tech at #io15.”
14.2 % men at Google I/O

Here’s the code lab I worked through.

Here are talks I watched later:

To tell even more of the story, here are all my photos from Google I/O, appropriately uploaded to the announced-at-I/O Google Photos, with captions.