Write the Docs Prague – Day 3 (Summary)

Standard

The following write up is about sessions I attended. I spent an hour or so mid-afternoon joining in one of the unconference sessions. A special thanks to Sarah Chambers for sharing her session notes.

After an excellent day of presentations and ideas, I was looking forward to another round of thoughts on writing, API documentation and customer support docs.

In the first talk of the day Pretty Hurts, Riona McNamara explained why better is sometimes better than the best when it came to quality. While it may be looked upon as effective to create documents in vast quantities, the quality of the documents is something that often gets overlooked. We don’t have an established vocabulary to talk about the quality of docs was the essence of her talk.

She spoke about the 2 types of quality

  • Structural quality – Focuses on the grammar, language, organisation and navigation of content.
  • Functional quality – Asks the more pertinent questions such as:
    • Does it do what is is supposed to do?
    • Does it satisfy requirements?
    • Achieve it’s objective?

Functional quality is harder to gauge than structural quality when it came to metrics. How do we achieve this?
a. Understand – State what the document should achieve or is supposed to do.
b. Define – Define functional requirements and get buy-in from internal and external stakeholders.
b. Execute – Create the docs keeping the requirements in mind.
c. Measure – Measure against requirements. Use quality data to communicate impact and value.

Given that almost everyone has used or use some sort of checklists (physical or mental), it was interesting to hear Daniel Beck talk about how he uses checklists in his daily schedule.
His statement “We live in a world where even the best people make mistakes – not because we are bad, but because systems become more complex and expectations increase” made a lot more sense after he showed some photos of flight cockpits and how they have evolved.

  • It is important that checklists contain completable and repeatable actions, instead of merely one to aspire.
  • You should design checklists with some context, such as thresholds or boundaries around what needs to be included.
  • Checklists usually fit a pattern – read-do or do-confirm.
  • Use the checklist to exploit existing habits, reward yourself or log your progress.
  • You can create physical checklists and add movement/sound to make it more dynamic.

Daniel demonstrated how he uses checklists to ensure automation is working by verifying, integrating and prototyping them. It was a very simulating presentation, especially about something we create frequently, but without giving it too much thought.

I am personally an avid reader and fiction is one of the genres I often fall back on to provide some mental stimulus away from work. The presentation by Thursday Bram on What Writing Fiction will teach you about writing documentation thus provided some excellent insight into how these 2 worlds could converge.

wtd2

This is what there is to writing documentation like fiction:

  • Write what you knowYou’re never going to know everything about your audience and your product. Even if you’re documenting code you wrote yourself, you’re going to learn things from the way other people use that code. Good writing gets a little personal — but you should make an active decision about whether they help the documentation.
  • Be Brief – Good writing is clean and clear.
  • Emotion matters – Instead of just writing out steps in an instruction, try and inspire the readers/users to make most of the inspiration. Use storytelling to add relevance, context and suggestions.
  • Kill your darlings – While we may be tempted to leave clever words in our writing, it is necessary to keep documentation simple and easy to follow for everyone.
  • Provide context – This can’t be stressed enough. Without context, users will have no idea of the why’s and when of the instructions.
  • Set a reading order – Setting a preferred reading order to guide the user.
  • Maintain the CanonThe concept of canon is crucial when talking about fiction series. It’s the idea of the core information that has to remain true over the course of multiple storylines, like where a character is from or which characters are in relationships. Similarly, for our documentation, it the stuff that is based on what’s actually going on with the product or service we are documenting.
  • Encourage fan fiction – “Creating a set of core or canon docs will provide a base for community members to start from, as well as give you a way to denote documentation produced in-house and by fans.” This will assist users on building a community of documentation around products.
  • Use Beta readers and workshops – Similar to creating beta version of software, it can be useful creating beta versions of documentation to gather feedback.
  • Reading and Writing are connected habits – This is perhaps the most important of all. The more widely you read, the better. An article here or a novel there can spark ideas — and I’m not just talking about ideas for good fiction. You can find new metaphors and new perspectives with every word you read. I have found this to be true when I write documentation myself.

Do you know the best people in the organisation to talk about what customers want? Not the trainers, or the developers or even the marketing people. The support staff have more interaction with the customers directly than anyone else combined. Why are we not engaging them with the documentation efforts then? In her thought-provoking talk, Documentarians and Support: Work Better Together, Sarah Chambers gave some great insights into doing exactly this.

  • Technical writers and support staff have exactly the same goal – to help customers perform a task. Technical writers + Support = Superpowers!
  • Support help writers close the feedback cycle perfectly by showing them where the users are having trouble finding docs, are unclear or do not exist.
  • Support can provide writers a lot of information about the users, behaviour, the way they use the product or the language they use

Speaking from her Online Support background, she explained some metrics that support can provide about effectiveness of your documentation (in addition to your doc metrics around page views, engagement etc):
a. Measure your self-service ratios – Self service ratio = (no of article views)/(no of tickets created)
b. Customer effort score – Use a scale from Strongly Agree to Strongly Disagree to respond and look at the distribution of scores (High, Medium and Low effort)
c. Ticket tagging – Tag support tickets by how-to questions (for writers), bugs (for developers) or feedback (for product owners). You can use this data to graph your work effort, distribution of issues.
d. Qualitative data – Make your support tickets topics match your documentation topics. Makes it easy to track and troubleshoot. Also helps with proving ROI on documentation.

How do we get the support team to work with the writers?

  • Use common tools that support can use to create first drafts of documentation
  • Provide them downtime to work on other projects such as documentation
  • Create a in-house style guide as a reference
  • Use the same workflow to progress a document
  • Provide the correct templates to support staff

Kata Nagygyorgy has been working on polling useful data around technical communications for some months now and she provided us with early insights. In an initial sample of 100 responders across NA, EU, AU:

  • There are around 30-40 names our documentarian community identified with, with Technical Writer as the most popular title for documentarians
  • 20% people got into Tech Writing by coincidence
  • Github has quickly grown to be the most popular, with Confluence, Text editors and Word as the most popular tools
  • 71% responders have and use an in-house style guide for their documentation
  • Markdown, XML and DITA are the most popular outputs
  • 66% responders self-review their documentation

You can use this form to fill in your stats: https://goo.gl/6SQc63

Unconference

wtd

I took some time off in the afternoon to network with other attendees and join an unconference table talking style guides.

While the term “unconference” is not new in itself, most conferences I’ve been to in the past, encourage attendees to mingle over breaks.

At Write the Docs, attendees who had an interest in hosting an unconference session could do so by putting up their ideas on a whiteboard at the start of the day and others could join in, providing a break from the intense presentations. I thought this was a real cool way for people to talk about topics close to their heart, be it coding, APIs, style guides, or search algorithms.

I joined in the Style Guides session where a group of attendees spoke about the pros and cons of style guides, what needs to be included/excluded, the “live” nature of style guides and how companies should encourage staff to contribute to style guides.

The key takeaway of this session was: Everyone needs a style guide. It makes life easier, documentation consistent and removes ambiguity around standards.

Advertisements

Write the Docs Prague – Day 2 (Summary)

Standard

The following write up is about sessions I attended. I spent an hour or so mid-afternoon taking a mental break or joining in the unconference. A special thanks to Sarah Chambers for sharing her session notes.

After a hectic Day 1 of contributing to, talking about, improving and creating new documentation via the sprint style action, it was time for the presentations.

In her welcome speech, Mikey spoke about how the Write the Docs movement has gained steam worldwide, the main driving factor being the true sharing-and-caring nature of the community. The community is not just about technical writers (even if they form the majority), but anyone who is involved in documenting, be it developers, support, testers or anyone else.

In his very uniquely named presentation Postulating the Backlog Laxative, Paul Adams essentially drew on his experiences to present a case for fitting documentation in a scrum. Coming from a life of playing rugby, he is quite familiar with the word “scrum” and expanded on it to provide some answers on the role of tech writers in a scrum. According to Paul, tech writers are either:

  • Not involved in a scrum, leading to no documentation at the end of a sprint or release.
  • Like a fish riding a bicycle, leading to communication overhead and distraction towards the tech writer. Tech writers could also be spending time writing for one person as opposed to the team, working against the very principles of scrum.
  • Involved in the scrum, but always out of sync by one iteration.

To solve this conundrum, Paul suggested keeping the tech writers out of the scrum, but in constant touch with the scrum team. His rugby analogy of having the tech writers like back runners provided justification that they don’t have to be in a scrum, but just work smoothly with the scrum team.

The 2nd speaker of the day, Istvan Zoltan Szabo provides some great insight with his very timely and needed talk Writing as a non native speaker. For a lot of tech writers in Europe, English is not the native language. Recounting his own experiences, Istvan threw light on the limits of language and how entropy creeps in our communication with using English, as he reckons that English does not have the same preciseness that some other languages provide for. He provided some very good examples to illustrate this point. To counteract this, he explains how he went about pushing his own personal limits, or stretching the borders to quote him directly.

  • Follow a process – Draft, Rest, Self-Edit, then send for review.
  • Stretch the borders of your language – Translate a book, watch a TV series, or get a coach/mentor and practice.

Ever wonder why they ask you to put on your own mask before helping your dependants on an airplane? It may have something to do with being able to make sure that you are in a position yourself before you help someone. In his very offbeat, yet very relevant topic Healthy Minds in a Healthy Community, Erik Romjin spoke about how important it is to identify, talk about and work on our private health in an increasingly connected community.

  • 70% of people regularly experience physical symptoms due to stress, yet they get away by hiding it under the pretext of being “just tired”
  • We are not mental health professionals (as a community), but we make a difference to someone’s well being by simply being empathetic and listening.
  • People love contributing to projects, but we often forget that we need to help ourselves before we help others
  • It is perfectly OK to say NO and it is ok to say NO MORE to things that you are already committed to
  • Suffering through our work serves no one, so it is necessary to let out some of that anxiety and talk to someone.Asking for help is not failing – it is as a matter of fact succeeding.
  • Build a culture that makes everyone feel they are welcome and that you are delighted to have them involved.
  • Show appreciation where due. It can feel uncomfortable to appreciate people, but it is always well received.

img_20160919_1241152

Lightning talks

Just after lunch, attendees were invited to present 5-min lightning talks on any topic. Slides were optional, so it was pretty much a chance to present an idea, discuss an issue, provide an answer, or talking about your product/tool/technique.
It was a very cool platform for people to build up confidence or address that stage fright or make a case for a future conference presentation.

If you thought software documentation was a tough gig with multiple approvals and non-forthcoming SME’s, Joan Wendt’s talk Documenting Data Center Operations demonstrated how hard it was to document operations documentation for field staff.

Presenting stories and non-classified artefacts from her work, she explained her workflow on how she went about attending design meetings, working in lab to photograph prototypes, accompanying engineers to first build site, creating draft documents, field testing the documents and then publishing the production versions. For some documents, she was required to get up to 20 levels of approvals before she published the documentation.

Given the nature of the documentation (instructions) and the audience environment (on-field), her documentation sometimes needs to be created with minimalist principles, and with clarity rather than including superfluous text or focus on formatting. Some of the more common challenges she faces:

  • Difficulty in getting knowledge out of some people
  • Strict security policies and up to 20 levels of approvals
  • Detail oriented documentation required.

As with other jobs, there are pros (travel, field testing possible, meeting end users, best practices) and cons (physically demanding, stressful, tedious work) to this type of doc work as well.

Creating meaningful interactions with users requires a strategic voice with a human tone“. In her talk Watch that tone“, Sarah Karp expanded on this quote and explained how voice (personality) and tone (mood) make for a good information experience. She cited some examples of Warby Parker and Mailchimp content that uses the correct voice and tone to guide the user.

In order to keep a consistent voice and tone throughout your documentation, it is important to:

  • Look at your company values and what stands out should be in your content
  • Be bold, optimistic and practical
  • Define your own individual voice

At Atlassian, the Information Experience Designers use something called Voicify cards that have guidelines for different scenarios. It is like a cheat sheet that sets the scene (for the content), provides tips and tricks, a feelings slider scale across the bold, optimistic and practical aspects of the content. It allows them to learn by example and gauge feedback. She summarised her talk with “Voice and tone builds trust – people know you and can identify you!“.

This was my first time at a Write the Docs conference as an attendee and presenter. Drawing up on my experiences (and frustrations) of bad screenshots used in documentation, I spoke about the why and how of screenshots and what we as tech writers could do, to address the issue.

img_20160918_0936124

Bad screenshots make a tech writer’s work harder, by adding to the content development time, plus the hassle of getting new and clear screenshots. One way to address this at the very outset is to have relevant instructions around capturing, naming, saving screenshots in the company style guide. Screenshots are basically the most effective when they are used with a specific purpose, be it to educate, complement or guide the user.

Documentoring is a thing, at least according to David Oliver, who uses it to mentor his engineering and marketing team members on the art of producing quality documentation. Documentation needs to be added to the definition of done in a product team. According to David, “documentation is a product. You cannot have one without the other.” This resonated strongly with a lot of attendees.

David Oliver spoke about 2 different cases:

  • Great product/flawed documents – In this particular case, while there was considerable interest early on, users became frustrated with the product particularly around difficulty in using the product. It became difficult to retain users.
  • Simple product/better documents – While the product was easy, users could get into all the features and the feedback was around improvements. Documentation made it a very good experience for the users.

In order to give yourself the best chance to succeed, it is crucial to use the same toolset (JIRA, Markdown, Github) as other teams. Also, sometimes it important to have documentation at 80% correct than 80% complete.

The key to good documentoring is: persistence, process, events, empathy. And donuts. They always seem to work.

Write the Docs Prague – Day 1 (Summary)

Standard

The Write the Docs community is growing. In leaps and bounds. No doubt about it. Their conferences (both the US and EU versions) have been a hit since they first started 2-3 years back. I admit I was a bit late to the party, but I am glad I had this chance to become a part of this community.

When I found out that the Prague conference dates coincided with my son’s school term break, I knew it was time to pack our bags and head to Europe. While this was the 4th Write the Docs conference in Europe, this was the second year in a row that the Write the Docs EU conference was held in Prague.

Day 1 – Writing Day

Day 1 of the conference was an official Writing Day. A huge, all-hands-on-deck style documentation sprint. Documentation sprints are a great way of getting everyone on the project involved contribute to the project documentation, be it internal wikis/knowledge bases or external user facing content. This allows everyone to get a taste of the documentation process and feel ownership of the content produced. Besides, if you are a tech writer, it adds immensely to your professional equity and builds on your network.

The first day saw a lot of attendees present at the conference venue at 9am sharp, surprising even the organisers. Breakfast, lunch and tea/coffee with snacks were included in the ticket. The writing day kicked off with 3 projects put up as needing help with the documentation:

  • Mozilla Developer Network – The MDN project was basically documenting how the web works. It was a very cool idea where anyone could contribute via new articles/tutorials, editing or proofreading existing content.
  • PyLadies Global – This project involved assisting with the PyLadies blog and working on a new Contributor’s Guide.
  • WikiMedia Germany, WikiData and SparQL – You could help with learning and documenting the WikiData Query Service, proofread existing documentation or document SparQL for end users.

img_20160918_1504470

Once the attendees had gathered their bearings post coffee, it was all business, with tech writers, support, developers chipping in with their best effort on their preferred project.
I met a number of tech writers, translators, editors and developers from Germany, UK, Romania, Ukraine and other parts of Europe. It was a really good, swapping stories and experiences.

  • I discovered that a large number of Europe-based tech writers face similar issues with employers as some of their Australian counterparts do – lack of knowledge about the tech writing profession, small and dispersed communities, plenty of startups offering good opportunities and availability of right tools for authoring and publishing content. (Regardless of who I spoke to, SharePoint was never looked upon with great enthusiasm I must admit).
  • A large number of attendees I spoke to were heavily involved in developer documentation or API/SDK content. In Australia, we do not see a lot of such roles regularly, unless you are already a part of companies who do this for their clients.
  • Surprisingly, a large number of attendees have never been part of traditional technical writing societies such as STC, TCUK, ISTC etc and instead favour more spontaneous meetup style activities or events to meet other people in similar roles.

At the end of a tedious day, attendees let down their hair and relaxed with a drink or two at the reception. I thought this was a really good way for everyone to acclimatise themselves and warm up for the conference sessions for the rest of the program.

About Prague

This is my first trip anywhere in Europe and no better place to start off than in Prague. Such a lovely, lovely city. My first impression was that it looked a little outdated, but you soon discover that is entirely its charm. Other places want to modernise themselves, but it is as if Prague set itself a challenge of keeping its heritage listed architecture instead, and succeeded greatly.

img_20160917_1836130

My family and I visited the enormous Prague Castle. Built well over 500 years back, it still looks very impressive and intimidating. The gardens surrounding the castle are equally splendid. Although it is a recommended tourist hotspot, there were not many visitors on a wet and cold Sunday evening, which made the visit feel very private and unique. We also did a 2 hour tour of the city on bicycles, which was immense fun as it led us down some interesting alleys and places that we would have otherwise missed.