Blog Archives

Report from Write the Docs Sydney

This week we hosted the first ever Write the Docs meetup in Sydney. It was great to see so many familiar faces and to meet so many new people too.

The Sydney meetup is part of the Write the Docs Australia group, founded by Swapnil Ogale. This was the Australia-wide group’s second meeting, after the kickoff in Melbourne in September.

The Sydney meetup

We had 22 attendees at the inaugural Sydney meetup. The venue was the Google offices in Pyrmont.

Write the Docs Sydney

Swapnil was an excellent host. Between the two presentations (see below) he asked attendees to introduce themselves and say what they liked most about technical documentation or being a technical writer.

What attendees like about technical documentation / technical writing:

  • I like to explain things.
  • The scope of technical documentation extends all the way from consumers to developers.

Write the Docs Australia

  • I like editing a doc when someone complains about it – that means they need it.
  • I like to help things go smoothly.
  • I’m married to a technical writer.

Write the Docs Australia

  • Technical documentation says exactly what it means. It cuts out all the fluff, even when describing an error in the product.
  • I get to do problem solving in a creative environment.
  • I like the ability to make the documentation a tool that someone can use rather than just read.
  • Technical documentation captures stuff before it’s lost.
  • I truly enjoy the research that goes in before writing the docs. Discovering bugs!

Presentation: Integrating more closely with software product teams

Craig Simms, from Campaign Monitor, presented a talk on how technical writers can integrate more closely with software teams. Campaign Monitor works off an agile development process. As processes change, the technical writing team must change to keep up.

Craig’s presentation was amusing and engaging. He told the story of how technical writing started at Campaign Monitor as a community building role, but it quickly became apparent that it was a core technical writing role. Quite quickly, the two writers in the company felt that their role description and placement in the company didn’t reflect the value that technical writers bring to an organisation. They decided they needed to join a product team.

Craig Simms, Campaign Monitor

Craig described the two years of adventure he and his co-writer have had, attempting to get into a product team. They’ve not yet succeeded, Craig said with a laugh, but he gave a zestful account of the lessons learned, and the steps they’ve taken towards that goal. One of the questions that’s arisen is this: Is product the right place for technical writers? An attractive alternative is to be part of the marketing team.

This quotation from Craig’s presentation in particular rang true with me:

Define your own value, and never stop telling people.

Here’s the recording of Craig’s presentation:

Presentation: Wrapup of Write the Docs Prague

Swapnil Ogale presented his summary and take-aways from the recent Write the Docs Prague conference.

Swapnil Ogale, Write the Docs

Swapnil talked about these topics:

  • Why he attended the Prague conference.
  • Attendee demographics – he showed a lovely picture of the venue and participants.
  • Range of topics covered – wide, including fiction and health!
  • A deep dive into 2 presentations he found most useful.
  • The unconference part of the event – spontaneous sessions on what people wanted to talk about.
  • Key takeaways from the conference.

An interesting statistic:

70% of participants are working on dev docs, APIs and UI text.

Here’s the recording of Swapnil’s presentation:

Where next for Write the Docs Australia?

I’ve been lucky enough to attend both meetings of the Write the Docs Australia group. Perhaps I can keep a good thing going and join the third, wherever it may be. Brisbane, anyone? 🙂

Musing about Write the Docs and ASTC and STC and more

So many options to choose from! As a technical writer in Australia, I can join a Write the Docs Australia meetup, the ASTC (Australian Society for Technical Communication), the US-based STC (Society for Technical Communication), and more. I’ve been putting some thought into the differences between Write the Docs on the one hand, and organisations such as ASTC and STC on the other. For me, they all have their place and membership of all of them is valuable.

I’m currently a member of Write the Docs Australia, and have also attended Write the Docs meetups in San Francisco, Silicon Valley and Portland. I’m a paying member of the ASTC and the STC, and support both by presenting at conferences or webinars whenever practical. I’ve also presented sessions at conferences organised by other bodies, such as TWIN and tekom.

Write the DocsFor me, Write the Docs differs from the more formal organisations in that it’s an informal community of people interested in technical documentation. The heart of the community is a series of meetups that happen in various parts of the world. There are also a few annual conferences. You don’t need to join an organisation – you just join a meetup, and then turn up.

Write the Docs is focused on documentation, rather than on technical writing. The community explicitly welcomes anyone with an interest in technical documentation. This includes technical writers, engineers, UX designers, support engineers, editors, and more.

The primary focus of Write the Docs meetups is API docs and developer tools, but other types of tech docs are becoming popular too. It’s up to us, the members of the community, to decide what we talk about.

So, for me, there’s a place for both types of organisation, even in a community of writers as small as Sydney or Melbourne. My aims are to share knowledge, learn, meet people, and spread good cheer.

And I haven’t even touched on the various social media groups and mailing lists on Slack, LinkedIn, LISTSERV, and so on.

What brought on these musings? The first Sydney Write the Docs meetup ever is at 6pm on Thursday 3rd November. Come along if you have an interest in, or a story about, tech docs – from any perspective.

Sign up here: https://www.meetup.com/Write-the-Docs-Australia/events/234610168/.

Have an idea for a talk for future meetups? Add questions or comments to this post, or add them as comments on the meetup page. Swapnil Ogale, the founder of Write the Docs Australia, would love to hear your ideas!

How to get started with Markdown and where to try it out

Technical writers have heard quite a bit recently about Markdown. Putting aside the question of whether Markdown is the right choice for technical documentation, it’s interesting as a tech writer to know more about the language itself. What is Markdown, where can we see it in action, and how can we try it out? Here are some pointers. If you have any other tips or stories about Markdown, I’d love to hear them!

Markdown is a markup language designed for quick and easy creation of simple documents. The syntax is pared down to the minimum, with the result that:

  • The syntax is easy to remember.
  • A Markdown document is easy to read, since much of the content is free of markup tags.

Along with the markup syntax, Markdown comes with a parser (a piece of software) that converts the markup to HTML, so you can display the document on a web page.

Other well-known markup languages are HTML, XML, reStructuredText, various forms of wiki markup, and many others.

Example of Markdown

Here’s a chunk of the above text in Markdown format, with an added level 2 heading, “What is Markdown?”

## What is Markdown?

[Markdown](https://daringfireball.net/projects/markdown/) is a markup language
designed for quick and easy creation of simple documents. The syntax is pared
down to the minimum, with the result that:

* The syntax is easy to remember.
* A Markdown document is easy to read, since much of the content is free of
  markup tags.

Along with the markup syntax, Markdown comes with a parser (a piece of software)
that converts the markup to HTML, so you can display the document on a web
page.

Equivalent in HTML

Here’s the same text in HTML:

<h2>What is Markdown?</h2>

<p><a href="https://daringfireball.net/projects/markdown/">Markdown</a> is
  a markup language designed for quick and easy creation of simple documents.
  The syntax is pared down to the minimum, with the result that:</p>

<ul>
  <li>The syntax is easy to remember.</li>
  <li>A Markdown document is easy to read, since much of the content is free of
    markup tags.</li>
</ul>

<p>Along with the markup syntax, Markdown comes with a parser (a piece of
  software) that converts the markup to HTML, so you can display the
  document on a web page.</p>

Getting started with Markdown

When I first encountered Markdown, I already knew HTML and the wiki markup syntax used in Confluence. For me, the best approach to Markdown was:

  • First quickly scan the most basic syntax elements, to get an idea of the philosophy behind Markdown and to pick up the patterns. I’ve included some pointers below, to give you an idea of the patterns in the syntax. Note, though, that there are variations in Markdown syntax.
  • Then find a good cheatsheet and refer to it whenever you need to check up on something. Here’s a good cheatsheet.
  • If something doesn’t work, consult the full syntax guide.

Where can you try it out?

The best way to learn is to do.

  1. Grab my Markdown code from above, or write some of your own.
  2. Paste it into the text box at the top of Dingus.
  3. Click Convert.
  4. Scroll down the page to see first the HTML code and then the rendered version (HTML Preview) of your text.

Basic syntax

Here are those pointers I promised, to get you started.

Heading levels

# My level 1 heading
# Another level 1 heading
## My level 2 heading
### My level 3 heading
#### You get the drift

Paragraphs

No markup, just an empty line before and after each paragraph.

Links

Put the link text inside square brackets, followed by the URL in round brackets.

[Link text](https://my.site.net/path/)

Another way of doing links is to define a variable for the URL somewhere on the page, and use that variable instead of the URL in the text. This is useful if you need to use the same URL in more than one place in the document, or if you want to keep the messy, long URL away from the text.

[Markdown] is a markup language,
blah blah blah - this is the rest of my page.

[Markdown]: https://daringfireball.net/projects/markdown/

Bulleted list

* My list item
* Another list item
  * A list item embedded within the previous one
  * Another embedded item
* An item in the main list

There must be an empty line before and after each list, otherwise it gets mixed up with the preceding or following paragraph.

Numbered list

There are a few ways to do numbered lists. Here’s one:

1. My list item
1. Another list item
  * An embedded bulleted list item
  * Another embedded item
1. An item in the main list

You can mix and match bulleted and numbered lists, with varying degrees of success. 🙂

More markup

There’s plenty more you can do with Markdown, and there are a couple of syntax varieties to trap the unwary. For example, GitHub has a special flavour of Markdown.

Recent articles about Markdown

There’s been a fair bit of discussion about the pros and cons of Markdown recently. Here are a few of them:

My opinion

In my day job, I write docs in both HTML and Markdown. I prefer HTML for comprehensive technical documentation. Markdown is good for very simple documents, but the syntax becomes clumsy for more complex things like tables, anchors, and even images. On the other hand, there are excellent benefits to using Markdown for quick collaboration on a document.

As is so often true, we need to choose the best tool for each use case. It’s a good idea to get to know Markdown, so that you can form an opinion and be able to use it when you need it.

First Write the Docs in Australia

The first Write the Docs meetup in Australia is happening soon! I’ll be there, to lead a discussion around working with engineers. Huge thanks to Swapnil Ogale for organising this first meetup ever in Australia.

The session will be in Melbourne at 6pm on Friday, 9 September 2016. Can you come? For more session details and signup, see the Write the Docs Melbourne meetup.

About Write the Docs

Write the Docs (WtD) is an informal community of people interested in technical documentation: technical writers, engineers, UX designers, support engineers, editors, and more. The heart of the community is a series of meetups that happen in various parts of the world. There are also a few annual conferences.

You don’t need to belong to any organisation. Just register for a meetup in your area of the world.

Topic for the Melbourne meetup: Working with Engineers

Swapnil Ogale is the organiser of the Melbourne WtD meetup. He’s invited me to lead the discussion at this first session. We’ll talk about working with engineers. I’ll start with a presentation (about 20 minutes):

How does a technical writer build a super-productive relationship with an engineering team? Sarah has some tips gleaned from working with engineering teams at Atlassian and Google. The tips range from co-location (a fancy word for sitting together) to capitalising on your core skills as technical writer (a sure-fire way of becoming a valued member of the team), and more.

Are engineers keen to update the documentation themselves, and what might prevent them from doing so? See what some engineers replied to these questions.

We’ll close with a group discussion where people can share their own ideas and experiences. If it’s easy, bring your laptop or mobile device along, so that you can contribute to a shared doc.

If you’re an engineer or have another role that touches on technical documentation, come and talk about working with technical writers!

 

Eliminating the zombie vulnerability – removing passive voice from the docs

If you can insert the words “by zombies” into a sentence, then that sentence very likely uses the passive voice. A colleague recently reminded me of this tip. It made me laugh, and so I thought it’s worth blogging about. If only to share the chuckle.

Here are some examples of zombie-infested sentences, and their equivalents using active voice.

Example 1

Geographic requests are indicated by zombies through use of the coordinates parameter, indicating the specific locations passed by zombies as latitude/longitude values.

Converting passive voice to active:

You can use the coordinates parameter to indicate geographic requests, passing the specific locations as latitude/longitude values.

For an even more concise effect, use the imperative:

Use the coordinates parameter to indicate geographic requests, passing the specific locations as latitude/longitude values.

Example 2

Latitude and longitude coordinate strings are defined by zombies as numerals within a comma-separated text string. For example, “40.714,-73.998” is a valid value.

Converting passive to active imperative:

Define latitude and longitude coordinates as numerals within a comma-separated text string. For example, “40.714,-73.998” is a valid value.

Why eliminate the zombie vulnerability?

Active voice is more concise than passive voice. It’s usually easier to understand.

To me, the most important point is that active voice makes it clear who’s responsible for what. Putting zombies aside, if you use the passive voice your readers may think that the nebulous “system” may do the thing you’re talking about.

Who does what, in this example?

The API can return results restricted to a specific type. The restriction is specified using the types filter.

Answer: The developer has to specify the types in the types filter. I don’t think that’s clear, though, when reading the text. Often the context makes it clear, but not always. Zombies lurk in the shadows, ready to grab the unsuspecting reader.

The distinction between active voice and imperative mood

In the above examples I’ve pointed out the difference between active voice and imperative mood. In technical writing, both are good. The imperative mood is particularly concise and clear, but in some cases it can come across as too abrupt.

Should we ever invite zombies in?

I think there are times when passive voice is OK, or even a good thing. Sometimes a sentence sounds artificial if you attempt to inject a subject. Sometimes the passive wording is a well known phrase that readers will accept and understand more easily than the equivalent active phrasing. For example, what do you think of this wording?

These community-supported client libraries are open-sourced under the Apache 2.0 License and are available for download and contributions on GitHub. The libraries are not covered by the standard support agreement.

%d bloggers like this: