Last week I ran the Kubeflow Doc Sprint, an event which brought open source contributors together from all corners of the world to write docs and build samples. We worked in groups and individually, chatting over video conference and on Slack, collaborating via online reviews and comments. We tackled complex technology which for some of us was entirely new. We learned a lot and achieved a lot.
Planning a large doc sprint may seem like a daunting task. Actually, it’s a large set of not-too-daunting tasks. The daunting bits are (a) knowing what the necessary tasks are, and (b) getting organised to complete the tasks. If you’re considering running a doc sprint, I hope this blog post gives you some useful pointers.
A bit about the Kubeflow Doc Sprint
A doc sprint is an event where people get together to write documentation. The time frame can be anything from a few hours to a few days. From past experience, I’ve found that three days is a good period to aim for. It gives people time to contribute a fairly sizable piece of work and to enjoy the experience of the sprint.
The Kubeflow Doc Sprint ran from 10-12 July. We had contributors working in groups in Kirkland, Sunnyvale, and Chicago, as well as individuals online all over the world. We produced around 35 pull requests. A pull request is a set of changes that related to a given goal. For example, one pull request may add a new document or update related content in a number of documents.
My post on the Kubeflow blog includes a list of the tutorials and samples we built during the doc sprint. The blog post also has some pictures of the people in the sprint.
Optional extra: Learning on the sprint
We decided to run some short, targeted presentations during the doc sprint, focusing on documentation best practices and UX. I’d had feedback from previous doc sprints that three days is a long time to be heads down writing docs. People need a bit of variety, and they like learning new patterns that are at least tangentially related to their day job.
These are the mini talks from our doc sprint:
- How to address the reader in technical documentation.
- Passive resistance.
- A short guide to writing well.
- Kubeflow: A First Impression.
- Guiding users through a journey.
The tasks involved in planning and running a doc sprint
Here’s a brain dump of the things that need doing. But every doc sprint is different. My top hint, before diving into the details, is this: Make a list. 🙂 Add all tasks to the list, big and small, as soon as they occur to you. Start with the tasks from this blog post – pick the ones that apply to your situation. Then add your own.
I used a spreadsheet to track the tasks for this doc sprint, but any tool will do, provided you can share the list with others, set priorities, and make comments on the tasks. And of course, you must be able to mark a task as complete. Ticking off a TODO is one of the best feelings in the world. Your task list from your first sprint will be useful for planning your next sprint.
Preparations two to three months before the event
Start planning early:
- Get budget approval, and check that your manager and team are happy with the idea of devoting time to the sprint.
- Set the dates. Make sure the dates don’t clash with other related events or with holiday seasons. Avoid any important product release dates, if you can.
- Book a venue. First, you’ll need to estimate the number of attendees you can expect. Be generous – it’s far better to have room to spread out than to be cramped.
- Decide whether your budget provides for swag (T-shirts!) and prizes. If it does, organise the vendor and any designs you need.
- Invite people to the sprint. I used a Google Form, which handily put the registrations into a spreadsheet for me.
- Generate enthusiasm and discussion. Make sure people know you are committed to the sprint. That will give them the confidence they need to go ahead with travel arrangements and setting aside time to work on the sprint.
- Order refreshments and meals, if your budget extends that far.
- Arrange additional power extensions and cables, so that people can charge their laptops.
- Start preparing a wish list of docs to write and samples to build. I started the wish list in a spreadsheet, then moved it to the project’s issue tracker to form the sprint backlog. Discuss the wish list / backlog repeatedly with your team and the wider community. Encourage them to add to the wish list.
- Prepare and share an agenda.
Style guide, templates, and sprinter’s guide
It often surprises me that people are so interested in style guides. As a technical writer, I know the value of style guides, but I have a sneaking feeling that other people find them tiresome. Not so! In a doc sprint in particular, people appreciate the guidance. It’s also useful for reviewers to have somewhere to point contributors at, rather than needing to repeat the same style corrections in every review.
People also need to know how to work during the sprint: prerequisites and setup, where the docs are, where the doc source is, how to preview their changes, and so on. Here’s an example of a sprinter’s guide.
Online communication channels
Communication during the sprint is key, particularly when your sprinters are distributed around the globe.
- Set up a video conference call at least twice each day on each day of the sprint, where people can talk about their progress, check whether their work may overlap with someone else’s work, and ask for help on blockers. Useful video conferencing apps include Google Hangouts, Zoom, and more.
- Have an online chat room going. We used a Slack channel dedicated to the doc sprint, in the existing Kubeflow Slack workspace.
- Use a collaborative online tool for reviewing contributions and for tracking work done. We used GitHub’s pull requests (a pull request is a collection of changes related to a particular goal) and issue tracker. Take a look at the Kubeflow documentation pull requests and issues in our GitHub repository.
- Encourage people to add detailed comments to their pull requests, reviews, and issues.
At the venue
It’s often easy to forget the practical things, yet for the participants these are key to feeling welcome and safe:
- Post signs showing people where to go. Cover all the important destinations: the room where the doc sprint is happening; the bathrooms; the exit; coffee.
- If participants have to sign in to the building or if they may have trouble finding the room, have two or more helpers who can escort your guests to the room.
- In your opening speech, tell people the essentials: where to find the bathrooms; whether food is catered or not; who to contact if they encounter difficulties; the agenda.
It’s a good idea to arrange a demo session at the end of the sprint. Give the participants the opportunity to showcase their work and to let you know whether they plan to finish off their work in the days following the sprint.
A demo session can be quite simple. Provide a doc where people can add links to their work. Devote the last two hours of the sprint to the demo session. Display each person’s work in turn, and ask the person to give a three-minute overview, something like this:
- Introduce yourself.
- State the goal of your doc in one sentence.
- Give a short overview of the content.
- Describe any problems you encountered.
It doesn’t matter if only a few people are ready to present a demo by the end of the sprint. The demo session gives a focus and a sense of excitement to the event. In particular, it lends momentum to the last day which might otherwise fizzle out. You can take a look at the sprint demos for the Kubeflow Doc Sprint.
Docs, or it didn’t happen! Write a report and/or a blog post describing the results your doc sprint. Tweet about it. Let people know it was a success, so that they’ll be keen to participate next time. Be sure to list the achievements of the sprinters. They’ve devoted time and effort to the sprint. For many of them, the results you publish will be useful in their performance reports.
If you promised T-shirts or other swag, remember to send them out to the participants.
Don’t assume people know something, even though you’ve already told them via email and in chat and in person… During an event, people get overwhelmed with information and noise and meeting new people and trying to understand new things.
So, tell people the most important things again and again, in multiple channels.
One of those most important things to tell people is where to find all the information they need. For our doc sprint, the source of truth was the Kubeflow Doc Sprint wiki.
I’ve written a few posts about doc sprints and doc fixits over the years. Skimming through the posts shows just how different each doc sprint is!
Do you have any hints you’d like to share?
Many people have run open source doc sprints. If you have any hints or links, please feel free to add them as comments on this post.
In an effort to understand an SDK, I found myself drawing diagrams. Just to get the concepts into my head, and to visualise the way the bits and pieces fit together. It turned out that those diagrams are useful to more people than just me. My diagrams became part of the SDK overview that I was writing.
SDKs are conceptual and tricky to grasp at the best of times. This one offered a couple of special complexities. I’d heard from many sources that people were having trouble getting started with the SDK.
My goals for the introduction to the SDK
What are the two complexities that I wanted to illustrate?
Firstly, there are a few different paths that you can follow to achieve your goal of using the SDK to build a machine learning pipeline. For this doc, my audience is fairly comfortable with machine learning, so that’s not the complexity in this case. But it is confusing that there are a few different ways of putting a pipeline together.
Secondly, your code at some stage ends up in a Docker container managed by Kubernetes. It’s not a given that my audience is well up on Kubernetes. And they almost certainly don’t know how the containerisation of their code relates to their use of the SDK.
The doc and diagrams
The doc is an introduction to the Kubeflow Pipelines SDK. It starts off with an overview of the packages in the SDK, then describes the four ways you can use the SDK to build a pipeline, depending on your starting point and your use case.
The first use case describes the most common usage of the SDK: creating pipeline components from existing code. The section starts with a diagram:
As you can see, the diagram has some minimal code snippets. Just enough to give readers a hook to attach more information to.
Note: The diagram in this post is a png file, but in the docs I’ve used SVG (XML). The use of the XML format means that we can internationalise the text, when the time comes to provide the Kubeflow docs in languages other than English.
After the diagram comes a more indepth description of the diagram, with more meat to the code. It’s still probably not enough for people to copy, paste, and start coding, but that’s not the goal of this doc. The goal is for people to gain a conceptual understanding of what fits where, and of when you’d use this particular workflow.
At the end of the section is an info box containing links to further information and examples.
The subsequent sections follow the same pattern:
- Diagram with minimal code.
- More indepth explanation with more code.
- Pointers to detailed docs and examples.
The design of the doc mimics the user interface design principle of progressive disclosure.
The doc starts by revealing the primary concepts and code patterns in each use case. That allows the reader to grasp the similarities and differences between the use cases.
Next, for readers who want to know more about a particular use case, the doc gives a little more information below the diagram. There’s just enough terminology and code to give people a good idea of what the workflow involves.
For novices, that level of information provides a logical compartment into which they can wedge their growing understanding. They can go away and look at more detailed docs, then come back and fit that new information into the right place in the use case.
For readers who are already experts in most of the required areas and just want to know how this particular SDK works, the information under the diagram may even provide enough context to start coding.
Lastly, for each use case the doc provides links to detailed information and examples.
Do people like the doc?
I wrote the doc because I’d heard people were having trouble understanding how to use the SDK. My initial reason for drawing the diagrams was for my own understanding. But then I realised that the diagrams would probably be useful to others too. I showed the diagrams to an engineer, and he agreed. I showed a draft of the doc to an intern who had just started learning how to use the SDK. He said the diagrams would have been extremely useful if he’d had them two weeks earlier when he was starting out with the SDK.
The doc is new, so it’s too early to tell how well it performs for a wider audience. I plan to check the analytics and ratings in a few weeks’ time.
Do the diagrams hit the right spot between too naive and too complex?
I’m sure there are improvements we can make in the way I’ve described the technology. We’ll iterative and improve over the next weeks and months, as we do with most of our docs.
Still, I think we should be careful to keep a certain level of naivety. After all, these diagrams helped me kickstart my understanding of the concepts involved in using the SDK. Other people reading the docs will be at the same level of not knowing stuff when they start out. We need to keep that level in mind. The curse of knowledge is a powerful thing!
This week I attended the STC Summit 2019, the annual conference of the Society for Technical Communication (STC). Thanks so much to everyone who organised, spoke at, and attended this event. It’s been rewarding and fun!
STC Summit was packed this year. There were more than 750 attendees and more than 100 education sessions over the two days of the conference proper, as well as a number of half- and full-day training sessions during the preceding weekend, and a half-day plenary session to close the conference.
The keynote presenter, Peter Morville, is a well known information architect and author. One of his books is Information Architecture for the World Wide Web, affectionately known as the “polar bear book”. Peter spoke about information design, cultural trauma, decision making, getting things done, and bricks-and-mortar architecture. This wide ranging talk made a fitting start to a conference about technical communication, in itself a varied and wide reaching profession.
Notes from sessions
With more than 100 sessions in just two days, there was no way I could attend all the sessions I wanted. Here are my notes from most of the talks I did attend:
- Website search with Apache Solr, by Scott Prentice
- Compassionate technical writing, by Robert Perry
- Headless CMS, IoT, and You, by Chad Dybdahl
- More than writers, by Alan Porter
- How analytics can change your world, by David Payne
- Mentoring and being mentored, by Carrie Sheaffer and Eva Miranda
- Optimizing your content like an engineer, by Sara Feldman
- The trending value of tech knowledge, by Tom Johnson
- Sketching is like technical communication, by Elizabeth Alley
- Improving docs and measuring quality, by Barbara Giammona
My presentation: Open source and Season of Docs
I presented a session about getting started in open source documentation. The talk also introduced the new Season of Docs program, which provides a framework for technical writers and open source projects to work together on open source documentation.
Photo from a tweet with thanks to @beckatodd.
The conference took place in the lovely city of Denver, Colorado, in the United States. Snow-clad mountains surrounded us. The weather was balmy for most of the conference, with clouds and snow threatening on the last day.
An innovative design for a table, on the 16th Street Mall in Denver. Even when there’s no-one sitting at the bench, it looks like a happy place to be:
Union Station in Denver:
The big bear at the Colorado Conference Center, next door to the venue of STC Summit:
More about Denver
If you’d like to see more pictures and stories about my trip to Denver, take a look at my bookworm’s blog: Bears and banks in downtown Denver.
Another big thank you to the STC Summit planning committee for a great conference, as well as to all the presenters and attendees who made this such a great event. It was a privilege and a pleasure to attend.
This week I’m attending STC Summit 2019, the annual conference of the Society for Technical Communication (STC). I’m blogging my notes from the sessions that I attend. Thanks and all credit go to the speakers. Any mistakes are my own.
Scott Prentice‘s session was titled Website Search with Apache Solr. The presentation covered an open source search platform, Apache Solr, introducing its features and showing us how to install the platform.
Solr is a wrapper around the Lucene indexing and search technology. It has a REST API and some native client APIs.
While Apache Solr is a vast and complex system, it’s not to hard to get in and get started.
A quick bit about search in general
Why add a search to your website? Having your own search helps you keep visitors on your site. You can allow people to use Google Search, but having your own means you can curate the search to your own requirements. Having your own search also gives you insights into what people are searching for, and thus into your content.
Types of search:
- Remote search service through a web form or API
- A custom search platform, which is what Solr is.
You can set up Solr in a standalone mode, or you can use SolrCloud, which is a collection of search engines spread across multiple servers. Scott showed us how to set up the standalone search.
The process is:
- Download and extract the installation file
- Start the server
- Test the server
Scott walked us through the process in more detail, which involved creating an installation directory and a data directory, editing a config file, and moving some files around.
Then he started the server from the command line (
solr start), and accessed the Solr admin page at a
localhost:// address in a web browser.
The next steps involved copying the default schema to create a collection (basically, an index), and adding some example docs as data for indexing. The default schema works, but it’s very broad since it’s designed to handle a wide variety of content types.
Scott walked us through the syntax of a Solr query. You’ll use the query syntax when constructing a search and also if you set up a panel of faceted search results for display as a navigation aid. The default response is in JSON format, but you can request XML or CSV instead.
Customising your search
After testing the search, you need to:
- Customise your schema to suit your content and your website’s needs. Your schema defines the fields for the index. Scott showed us how to create a very simple schema, and how to apply it to your Solr installation.
- Generate a JSON or XML feed from your content, based on the schema. There are various web crawlers available to generate the feed, such as Apache Nutch, Heritrix, GNU Wget, and more
- Upload the feed to a Solr collection.
Scott mentioned CORS (Cross-Origin Resource Sharing), which you’ll run into when trying to read data from a remote server. The server owner has to enable the reading of content. So you need to enable your Solr server, by adding a config file. Scott recommends this blog post for help with setting up CORS.
Scott also gave us some tips on securing and scaling your Solr server before taking it to production. You can also consider using SolrCloud.
Thank you Scott for a useful quick introduction to Apache Solr.
This week I’m attending STC Summit 2019, the annual conference of the Society for Technical Communication (STC). I’m blogging my notes from the sessions that I attend. Thanks and all credit go to the speakers. Any mistakes are my own.
Robert Perry’s talk was entitled Technology for Good: Helping Organizations Do (More) Good with Technology. He spoke about how his organization has created solutions to make technology available to non-profit and educational organisations. He also introduced us to the concept of compassionate technical writing.
These are the primary points in Robert’s task
- Embrace Industry 4.0 in your career and writing. (Industry 4.0 is also called Fourth Industrial Revolution, FIR, or Information 4.0.)
- Use technology responsibly and for social change.
- Create content that people can learn from and relate to.
Challenges and opportunities in Industry 4.0
We’re already living the Fourth Industrial Revolution, says Robert. Innovations are transforming the world we know, and changing how we work and play. This is how Robert characterised Industry 4.0:
During the session, Robert talked us through the first (steam in the 1700s), second (electricity in the 1800s) and third (computing in the 1900s) industrial revolutions. Each of these triggered profound changes in society.
Then he focused on Industry 4.0. It has benefits and disadvantages. It’s disr
Industry 4.0 is moving far faster and is having a wider effect than any of the other three revolutions. It’s affecting almost every country and society. Technologies include biotechnology, robotics, 3D printing, Internet of things, artificial intelligence, virtual and augmented reality.
These technologies are also changing customer expectations. Customers expect more valuable connected experiences, personalised content, and contextualised content. Customers are not afraid to move to a different provide to get those.
Technical writers can help improve the customer experience. New categories of jobs are arising at the same time as others disappear. New opportunities are becoming available.
Customer feedback is becoming crucial, as is creating personalised, contextualised content delivery. There’s lots and lots of data coming in. Data feeds artificial intelligence, which can help make businesses and documentation smarter.
Trends for technical communication:
- Intelligent content
- Automated content generation
- Dynamic delivery of content
- Neural machine translations
- Service-oriented content rather than document-based product manuals
- And more
Robert said that metadata will drive many of the content delivery models. Metadata will become richer and more complex.
Technical writers will become knowledge managers – people who curate information, and enable the delivery of data-based dynamic content.
Technology for good
People must own the shaping of technology. Businesses are at the forefront, so they should also drive the sense of social responsibility. These are some of the things a business can drive:
- Education and training programs for all
- Ensure equal pay for equal work
- Equality for every human being
- Protecting our planet
There are hefty moral implications for these new technologies, for both good and bad. We build the things we admire, so we must make sure we understand the implications of what we build. We need to ensure that the economic benefits are available to all, not just to a small group.
Compassionate technical writing
The doc team at Salesforce (Robert’s employer) has started an initiative to write docs that show awareness of the customer’s situation. So they’ve started telling stories.
They ask themselves whether they write with a real human understanding of what it takes to use the product. Are we inspired and passionate about our work? Do we feel connected with the user?
Remember that readers should experience patience and compassion while they read. They may be in the middle of a frustrating experience.
How to write compassionately?
- Be yourself.
- Tell a story to help people identify with the documentation.
- Take care of your reader.
- Don’t force it on them. Be judicious – some areas of tech writing don’t lend themselves to compassion.
- Anticipate the questions your reader may have, and answer them.
- And more points from Robert.
The primary point is that every document must be technically accurate and excellent.
Robert recommends a book by Ann Handley, “Everybody Writes”.
Thank you Robert for a thoughtful look at technical communication and our changing world.