Sarah Maddox's Blog, page 17

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.

Set size of browser inner window for screenshots in Chrome

I need to set the size of my browser’s inner window, so that I can take screenshots that fit into a specific area and have consistent dimensions. After doing a bit of searching and experimenting, I found that you can do it nicely with Chrome Developer Tools. This is handy, because Developer Tools are a standard part of the browser. There’s no need for any add-ons.

Here’s how to set the dimensions of the inner window (viewport) in Chrome.

In short

Open Chrome Developer Tools.
Click the Toggle Device Mode option near top left of the developer tools section.
Choose Responsive from the dropdown menu at the top of the screen.
Edit the dimensions, which are also at the top of screen, right next to the dropdown.

The longer version

The screenshots show Chrome version 49.0.2623.110 m.

1. Open Chrome Developer Tools.

Press Option+Command+J on a Mac, or Ctrl+Shift+J on Windows, or open Chrome’s hamburger menu and choose More Tools > Developer Tools:

The Chrome Developer Tools panel opens in your browser. By default, it opens either at the right-hand side or at the bottom of your browser window. It can also open as an independent window. I have mine set to open at the bottom.

2. Click the Toggle Device Mode option near top left of the developer tools section.

The icon for Toggle Device Mode looks like a mobile device snuggling up to a larger screen.

3. Choose Responsive from the dropdown menu at the top of the screen.

When you’re in “toggle device” mode, a dropdown menu and editable screen dimensions appear at the top of the window. Make sure the dropdown menu is set to Responsive.

4. Edit the dimensions, which are also at the top of screen.

The dimensions are editable when the dropdown is set to “Responsive.” You can also set the relative size (100% in the screenshot).

That’s it. Happy screenshotting!

Where does Screeny put the recorded video or image file?

I’ve been experimenting with Screeny by Daeo Corp. Software, for recording screencasts on a Mac. It works well, but it took me ages to figure out where the app saves the movie or image files.

Here’s the answer: Screeny creates a “Screeny” directory inside your “Movies” directory, and puts the files there. They’re .mov files.

~/Movies/Screeny

​Here’s an example file name:

Screeny Video 26 Mar 2016, 5.47.45 AM.mov

​Here’s what the directory looks like in Finder:

Screeny puts the files in that directory as soon as you stop recording. There’s no way to change the default location of the files.

​What about single screenshots? Screeny puts those into a Screeny directory in your “Pictures” directory:

~/Pictures/Screeny​

​Example file name:

Screeny Shot 26 Mar 2016, 6.09.59 AM.png​

I hope this helps you find your screencasts. :)

Playing with Corilla, a new tech writing tool

David Ryan and team have just announced the first beta launch of Corilla, a collaborative publishing tool for technical writers. Huge congrats! This is a big milestone for a new product. The Corilla team are inviting us to try out the beta release and give them feedback, as a way of helping build a great product for tech writers. So, here goes. I’ve had a lot of fun playing with Corilla, building my first doc set.

I created a Corilla collection, which is a set of topics for publication. I didn’t have any real idea of what I’d write about. I just clicked get started today on the launch announcement and took it from there. It’s a smooth getting started experience. My only question was the significance of the team name during registration. I entered a team name of “DocsFTW”, on the premise that nothing can go wrong with a name like that. :)

My first cruise with Corilla

After registration, the welcome screen has a nice greeting and useful information on how to get started:

Next I clicked through to Topics, then New Topic, and got this dialog:

,

Nice: Context-sensitive help appears in the form of popups on the right-hand side of page when you open a section of the app for the first time (not visible on my screenshot). You can also click the help icon at bottom right at any time.

There’s more context-sensitive help within the UI itself, as you can see in the above screenshot. The wording needs a bit of tech writer love: It should probably say “for example” or “e.g.” rather than “i.e.” and the language in the suggested topic title isn’t quite right.

Something cool happened when I positioned my cursor in the Title text box. Corilla suggested two titles: “Working with an engineering team”, and “The future *is* technical communication”. These are two presentations I’ve worked on recently (both as Google Docs presentations). It’d be interesting to know how Corilla got those names.

So, thanks to Corilla for giving me a good idea of what to write about! I decided to copy some content from my presentation, “Working with an engineering team”, into the Corilla editor.

The Corilla editor uses Markdown, which is a lovely restful format for those of us who use it regularly. If you haven’t used Markdown before, now’s your chance. It’s a trimmed down markup format, great for simple online doc output and easy to read in its raw form.

After creating a few topics, the next step was to add some of my topics to a collection, which is the unit that Corilla makes available for publication. There’s a nice drag-and-drop feature for adding topics (on the left) to a collection (on the right):

Here’s the published result, which you can see online at the Corilla viewer: Working with an Engineering Team. The following screenshot shows part of the page:

It’d be nice to have the topic titles more prominent in the HTML output, with an indication of where the title fits into the page. Currently the output appears as one long page, including all topics. The topic titles are on the left, but it’s not clear which bit of text they belong to. The only indication of a topic break is a horizontal line, such as the one above “Teamwork is key…” in the above screenshot.

You may notice that my published output has some weird characters every now and then. For example, instead of “It’s” you’ll see this:

It’s

That’s because I copied my content from a rich text editor into the Markdown editor. I wonder if there’s some way Corilla can detect and correct such nuisances?

One more suggestion for the Corilla team:  A user profile is identified by an email address, and the email address appears at the top right of every page. It’d be nice to have a name instead, both to make the experience more personal and to hide the email address. (I’ve adjusted mine in all the screenshots on this page.)

Congrats Corilla team!

Congrats to the team on the beta launch! The launch blog post describes upcoming features:

In-line contextual formatting
Views for version control diffs and merges
Bulk importing/exporting
Multiple format outputs (ePub, PDF, other APIs, etc)
Media and file management
Slack integrations (among others)
Improved onboarding and documentation
Editorial and QE modes
Published content analytics
Improved multi-author mode
Customisable CSS on published collections

I’m looking forward to seeing more on the collaborative editing and version control side of the product. And content analytics will be very cool too. I hope the team gets lots of good feedback from the technical writing community!

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.

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. :)

tcworld India 2016 wrapup

This week I attended tcworld India 2016 in Bangalore. It’s been an amazing, rewarding experience. Here are some of my impressions, and a roundup of the posts I’ve written about the sessions I attended.

Tcworld India is an annual conference run by TWIN (Technical Writers of India) and tekom Deutschland. This is a great event, attended by 350 energetic, knowledgable technical communicators.

In his introductory speech at the start of the conference, Akash Dubey said that the great thing about tcworld India is the learning that happens in the corridors. That is so true! At every step, I met people with things to discuss, things to show, questions to ask, answers to propose.

The stage before the start of the conference, awaiting words of tech comm wisdom:

The sessions

There were 8 time slots on each of the two days of the conference, with up to 4 sessions running in each time slot. In total that makes approximately 30 sessions, covering topics across a range of areas: content strategy, tools, technologies, trends, usability, authoring and editing, structured writing, career development, leadership, localisation and translation, and more.

The following posts contain my notes about the sessions I attended:

The future *is* technical communication. (This was my own presentation, the keynote address on day 1 of the conference.)
The Future is Intelligent Information. (The keynote on day 2 of the conference, by Michael Fritz.)
Technical Writing for Big Data Applications.
Human Auditory Processing and Speech Recognition—Potential Latencies and Benefits for Documentation.
Predicting User Questions to Build an Information Repository.
Collocations and Phrasing in Technical Writing and Translation.
Accelerating Tech Comm Career Paths.
When Bad Design Happens to Good People.
Are YouTube and Google Making Technical Writing Redundant?
Introduction to API Technical Writing. (This was my tech talk, on day 2 of the conference.)

Bangalore

The conference took place in Bangalore, India. My travelling bookmark has some impressions of the city to share: Bangalore peace and traffic.

Thanks

Thank you to the organisers of tcworld India 2016, for a very well planned event and a skilfully constructed program. The care that you put into this conference is obvious. Walking around the halls, I saw happy, busy, engaged attendees and packed sessions throughout.

The party!

Technical communicators in Bangalore sure do know how to throw a good party. The venue was beautifully decorated:

We started with a few song and dance numbers from some very talented technical writers. I filmed some short videos, which capture the spirit and beauty of the event:

Another dancing item:

There was so much more. Guitars:

A sax:

Singers:

A huge thank you to the performers who put so much effort and talent into the show. I was blown away by the beauty of it, and so were all the attendees. Talented technical writers indeed!

After the show, the rest of the crowd got into the dancing scene:

Thanks again, tcworld India 2016!

API Technical Writing – tcworld India 2016

This week I attended tcworld India 2016 in Bangalore. What an amazing experience! I’ll write a summary of the conference soon. First, here are some notes on a session that I presented at the conference: “Introduction to API Technical Writing”.

The slides for my presentation are available on SlideShare: Introduction to API Technical Writing (slides).

Presentation overview:

An introduction to APIs.
An overview of the role of API technical writer, and of our audience – the developers who need our documentation to use
APIs in their applications.
A technical writer’s view of the types of API we might document.
Demos of 2 APIs that you can play with yourself.
The components of API documentation.
Examples of good and popular API documentation.
Working with engineers.
Tips on getting started as an API technical writer.
Why API technical writing is a good field to be in.

Thank you so much to everyone who attended the talk. The room was packed to overflowing. After the session, and indeed throughout the conference, people came up to discuss the field of API technical writing and to show me things they were working on. A number of conference attendees do API documentation as part of their role, and it was very interesting to see the variety of requirements even in this niche within a niche: API documentation within the technical writing profession.

For the next tworld India, I think it’d be a good idea to have a panel discussion on API documentation. We could invite 3 or 4 people working on different types of APIs, and within different environments (such as internal versus external documentation, or integrations).

Are YouTube and Google Making Technical Writing Redundant? tcworld India 2016

I’m attending tcworld India 2016 in Bangalore. The last session of the day was a panel discussion with the enticing title, “Are YouTube and Google Making Technical Writing Redundant?” The moderator was Edwin Skau. These are my notes from the session.

Note: By “Google”, the panel means Google Search.

Edwin started by saying that for the past few years, there have been prophets of doom foretelling the end of our discussion. In the age of YouTube and Google, what is the role of technical communication.

The panelists were Rajesh Chandrasekhar,Nihal, and Parveen Mittal.

Rajesh Chandrasekhar kicked off the discussion. He thinks the answer to the question is, it depends. If you think of the job as someone who publishes, then yes, your job may go away. But if your job is to make sense of the information out there, and to understand users’ problems, then our job will remain. Writers become curators of information. We collaborate on putting the information together – see the world of wikis. It’s a deeper understanding of the customer workflow that enables us to put documentation together. Rajesh showed us a configuration guide compiled from infographics, as a simpler, visual way of absorbing information.

At this point, there was discussion from the floor about the practicality of video guides.

The next panelist was Nihal. For apps, you need a nice way of describing what the app does, said Nihal. He gave 2 examples. A friend of his wanted to connect his phone to Nihal’s car. It was a very complicated procedure, and in the end they couldn’t do it. So they examined the user manual, which was a very thick book. Couldn’t find the information. So then they searched on their phones, and found a YouTube vide that helped them find the answer and do the task within 5 minutes. The video didn’t come from the car company, but from a third party.

Nihal’s second example was a game app that he was playing. He had an issue with adding another player to the game. On the website he found documentation in a question and answer format, and found the answer very easily.

So, in one case, YouTube was the answer, in another it was a technical document.

As a third example, Nihal described a product of his own, which helps people find each other in a certain environment, such as in a conference. He’d explained this app so often, but still the same answer came up: what does the app do. So he created a YouTube video, which does the job well. To create the video, he used a group of creative writers. So no, YouTube does not mean the death of technical writing.

The third panelist was Parveen Mittal. He decided to flip the question, and see what opportunities there are for technical communicators. YouTube and Google are additional channels that we can use. When you need serious information, you need technical writing. He thinks there are massive opportunities, but he’d like to wait for questions before sharing his thoughts.

There was quite a bit of discussion around dating sites at this point, Kinder, eHarmony, and other ways of connecting people. I have to confess I got a bit lost about the relevancy here.

Parveen thinks the amount of work for technical writers will not be reduced. There’ll always be a requirement for some documentation. Edwin made the point that in some cases, there’s a legal requirement for documentation. Regardless of the delivery mechanism for content, someone still needs to design the information.

A member of the audience pointed out that she and many people needed a starter manual, when getting a new product, so that they can confidently start using the product without being afraid of spoiling it or breaking it.

Rajesh pointed out that when you get an iPhone, there’s no manual that comes with it. The expectation is that the design is so good, no documentation is required. A member of the audience pointed out that technical writers are getting involved in the user experience design, that enables such great product design.

Edwin brought curation of user-generated content, and crowd sourcing, into the discussion, asking what the advantage is. Rajesh said the advantage is that you’re making use of the experience of the people out there. Edwin pointed out that there are users who have been using the product for longer than most employees have been with the company that designed the product.

Nihal pointed out that the ability to express the user’s requirements and write clear, useful documentation will always be useful.

A member of the audience said that a study had showed that 75% of the features of a product aren’t used as designed. How do we determine what the customer wants, and how the customer will use the product. Parveen said that crowd-sourced and collaborative technical writing plays a part here. As the UX becomes simpler and the underlying technology becomes more and more complex, you need crowd-sourced answers to issues that arise. Someone else will have had the problem you encounter, and will have solved it.

If technical writers try to stick to writing PDF documents in a dark corner (an analogy that’s been used a few times in the conference) then we’ll become outdated. But if we’re willing to change, there are plenty of opportunities open to us.

A question: Do you think there are limitations to search engines, such as Google, that are preventing users from finding information. Is this so, even though the algorithms are so good, and what can we do to solve the problem? Rajesh suggested running the search engine against your own company’s database, find any shortcomings, and improve the search engine.

Edwin closed by saying that we all agree. Yaayyy. He also suggested that we should consider writing outside our jobs, expanding our skills, and providing information in the places where people are looking for it. So, technical communication is a field that is growing with all these changes, not shrinking.

The consensus was that our profession isn’t going away. Yaayyy.

When Bad Design Happens to Good People – tcworld India 2016

I’m attending tcworld India 2016 in Bangalore. Edwin Skau gave a presentation entitled “When Bad Design Happens to Good People”. These are my notes from the session. All credit goes to Edwin, and any mistakes are my own.

Edwin started by saying that he focuses on how people think about what they do, rather than teaching people how to do something.

He told the story of the Steve Harvey, who mistakenly announced the wrong winner of Miss Universe 2015. Edwin showed us the card that Steve read the winner from, and we discussed how the design of the card led to Steve Harvey’s mistake. The mistake could have been prevented with better design. When bad things happen to good people, good people fail.

We looked at some definitions of design, and settled on this: “Design is a decision or decisions made to achieve a specific purpose.”

The purpose of training is to change behaviour. The purpose of technical communication is to empower users. Bad design leads to failure.

We looked at some hilarious examples of bad designs. An ATM that was high on a wall, and thus out of reach. Funny, frustrating error messages. Edwin had the audience giggling and even roaring with laughter. Then we saw an example of good design: a gadget that helps you put the pleats in a sari.

Jared M Spool talks about 3 approaches to design:

Self design – design something to suit the way you would use it. This often fails, because often you’re designing for people who are not like you.
Unintentional design – the design is forced by a decision made by someone at some time.
Research-based design – this is the best form of design. It’s based on user research: what the user uses the product for, what their win factors are, and so on.

Edwin discussed the features of good design. A well designed product is functional, useful, aesthetically pleasing, intuitive (making a user manual unnecessary), honest, and durable.

What about failures in information design? Edwin gave some examples, from some projects he had seen. These are some of the examples he mentioned:

Tabbed pages. Tabs hide information.
XML tags for every style.
PDF files produced from XML, where all topics of a particular type (concept, task, reference) are sorted together. This results in a guide that fails to help a user with a particular type.
Choose a tool first, then build a strategy around it.
Content sorted in alphabetical order by title.
Document the features, not the usage.
Forcing documentation into sprints. This can lead to over-documenting, and documenting what the developers have done rather than what the users will do.

You need to design the documentation process based on what you want to get out of the: where are we now, where are we going, what’s the most efficient way to get there from here. You must also figure out what you should not do.

A closing thought from Edwin: Quick wins are often the enemy of long-term gains.

I loved Edwin’s style of telling stories to illustrate his points. Thanks Edwin!