Home »

Write the Docs Newsletter – December 2018

Hi, everyone, and welcome to the last newsletter of the year!

What a packed year it’s been - with four conferences, and more meetups than I’m going to try to count. If you missed our most recent conference, Write the Docs Australia, there are tons of ways to catch up:

Looking forward to next year: the Call for Proposals for Write the Docs Portland has just gone up! It’s open until midnight PST, 17 January 2019, so get cracking and send us all your brilliant talk ideas. For full details, here’s the announcement post.

The newsletter team is off next month for Christmas (it’s snowing here already and I am super excited); we’ll be back in your inboxes in February. Happy holidays, everyone!

Here’s what we’ve been talking about on Slack this month:

Discovering user needs

Understanding what users need is at the heart of good technical writing. A recent question about how to determine user needs led to tons of ideas about who to ask, how to ask, and what to watch out for:

  • Ask your colleagues: product managers, support/success teams, developers…

    Product managers often have wide knowledge about user needs. Support can tell you about big and small customer pain points. Developers - particularly experienced ones - can give you insight into use cases, and the needs their code seeks to address.

  • Also try reviewing support tickets, for a detailed view on how users really work with the product.

  • Take a look at customer requests, and analyse them carefully. You want to distinguish between what customers ask for, and what they actually need.

    If you step back, you may realise that behind a specific request, there’s a better solution to their problem – teleporting as opposed to a faster car was one humorous example.

  • Dig through StackOverflow for questions tagged with your product (or related keywords).

  • Communicate with users to let them know that you’re working on their issues. Even if it’s not strictly speaking a docs issue, your communication skills can help product management and support reassure customers who are waiting for new features.

Technical writing career paths

There was a big discussion this month about how to define career paths for tech writers. Even the term itself was controversial, spanning two related ideas:

  • How a company defines levels of a role (also called a “career ladder”).

    This could be levels like Associate -> Senior -> Principal/Lead, or Technical Writer Level 1 through 4 (or higher).

  • Where you personally go in your career.

    This isn’t bounded by your organisation’s ladder: your path might involve changing company, or role.

Some participants thought the idea of a career path is tied to leadership: you don’t have a career path if there’s no route to C level. There were two counter-points here: firstly, you can have a path without that as your goal. Secondly, there are many routes to leadership, not necessarily defined by a ladder - for example becoming a product manager, and moving up from there to C suite.

Career ladders vary a lot. Bigger companies may have different “tracks”, for those who want to move into management and those who want to stay as individual contributors. In smaller companies, you might struggle to become a tech writer manager if the company doesn’t need a large docs team.

It’s important that ladders have well-defined levels. For example, if you move up after a fixed number of years, the change isn’t so meaningful. For better ideas on progression, take a look at junior vs senior technical writers.

Ultimately, your career is a combination of the path you want and the ladders available: it’s a collaboration between you and your company.

Grammar and style questions

This month came with a spate of language usage questions. We love getting these, so go ahead and post them in #general, but other good places to check came up:

Possessives and apostrophes

What’s the possessive form of “someone”? It is “someone’s” - the possessive of indefinite pronouns (like someone, anyone, everyone) use an apostrophe. Not to be confused with possessive personal pronouns (like its, mine, yours) which don’t use apostrophes.

Punctuation and quotation marks

Most US style guides say that commas and periods always go inside quotation marks. Whereas British style guides say they only go inside if the punctuation is part of the quotation. So it depends on your audience; take a look at this post for a bunch more detail.

Capitalisation

Should you capitalise “Boolean”? It came from a proper noun (named for George Boole), which implies it should be capitalised. However, developer audiences are used to seeing “boolean”. Decide which will make sense to your audience, then stick to it!

“Internet” versus “internet” also came up - another one that varies between style guides. (However, the correct opinion is “internet” – Ed.)

Resources for learning tech writing

Some of our tech writing beginners asked for suggestions of where they can learn more. Our documentarians had these suggestions:

There was one book suggestion too: Janet Van Wicklen’s The Tech Writer’s Survival Guide: A Comprehensive Handbook for Aspiring Technical Writers.

New tech writers and documentarians can also check out the #learn-tech-writing channel.

Community events coming up

Highlights and thanks from the Australian conference   Announcing Prague 2019 Conference Dates