Home »

Write the Docs Newsletter – November 2017¶

Happy November everybody! Kelly O. here, reporting live from the coffee shop that is about to cut me off because I’ve had three flat whites in a row. But I’m considering them celebratory beverages, because we have a jam-packed month of documentation goodness to talk about.

In the next few weeks, the organization team will be:

Announcing the call for proposals (and looking for volunteers) for next year’s Portland conference! (If you’re not signed up to the conference mailing list, you can do so here.)
Wishing we were all going to be in Australia for their Write the Docs Day mini-conference.
Looking on excitedly as API the Docs holds their second one-day event in Amsterdam.
Musing on how we got so lucky as to have almost a dozen meetups this month in a cities across the western hemisphere.

Of course, in the meantime, we also have an array of documentation stories below, for your reading pleasure. Enjoy!

Worth it: images & screenshots¶

This month, we had a couple of conversations about images and screenshots that raised some interesting questions. When do we need to include images in our documentation? How many images is enough? How many is too many? Given how difficult they can be to maintain, are they even worth it?

Of course, our community of documentarians had a variety of good answers to share. For starters, there was a consensus that screenshots are inherently challenging. They take a significant time commitment to maintain, especially for a product with frequent UI changes. It was also pointed out that they are often overused and may not even be that useful to our readers. Diagrams, on the other hand, can be incredibly useful when designed well. Overall, the feeling was that using some screenshots and other images in your documentation is usually worth it, especially if you can commit some bandwidth to maintaining them.

Some other image tips that came up included:

Crop your screenshots to highlight only the specific area of interface you’re documenting.
Keep all of your image files in a single, separate location. If possible, use version control.
Develop – and stick to – a standard for producing screenshots: size, tool, resolution, file type, etc.
Triage your updates. Prioritize functional UI changes over changes in button color, for example.

A `{}` by any other name¶

Sometimes, when scanning Slack, it’s easy to spot which comments are going turn into newsletter fodder. Other times, a trivial comment will unexpectedly blow up. This month, what started as a quick ‘hey, what’s the name for this punctuation mark?’ turned into a surprisingly in-depth and entertaining discourse.

For many of us, our primary use of {}, [], and () is in code. But what you might not know is that a) there is a dizzying array of names for these marks and b) when using them in prose, they have some interesting uses you might not be familiar with.

Just in our own Slack community, people said they refer to {} as squiggly brackets, braces, curly brackets, curly braces, and (totally seriously, I’m sure) curly wurly woos. If that’s not enough, the wikipedia article on brackets is not only a hilariously deep rabbit hole, but also provides us with more names including: French brackets, definite brackets, swirly brackets, birdie brackets, Scottish brackets, squirrelly brackets, gullwings, seagulls, twirly brackets, Tuborg brackets (DK), accolades (NL), pointy brackets, third brackets, fancy brackets, and m braces.

As for their use in prose, as opposed to code, someone shared a Grammar Girl article, which digs into the various proper usages for () and []. (Curly wurly woos don’t come up much in prose, so the post doesn’t touch on them much.)

So remember, for the Write the Docs hivemind, there is no question too big, and no question too small.

It’s your turn to ask the questions¶

We’ve all fretted over what we might be asked during an interview. But what about when it’s our turn to ask questions? This month, a job-hunter sparked a great conversation about what to ask in an tech writing interview. We’ve written up a few highlights:

Show them you know your job. Asking specific questions about their expectations and processes can get you into the nitty-gritty, and give you a chance to show off your chops. This blog post has some good examples.

Don’t be afraid to follow up. If something they say raises a concern – or just piques your curiosity – loop back to it when your turn for questions comes.

Ask what they think of your resume. Directly asking about your application materials gives the interviewer a chance to ask about your background, and you a chance to clarify or crow about your previous roles.

Have a couple backups. Some of your questions will be answered in the course of the interview, so come prepared with spares.

Clarify next steps. When the interview is wrapping up, make sure to ask when you can expect to hear from them. If they don’t give you a firm date, tell them you’ll follow up in a week.

The bottom line is to remember that you’re asking questions to help you figure out whether the job is a good fit for you too.

To automate, or not to automate¶

One Slack contributor’s triumphant story of automation success sparked a thoughtful series of posts about when and how to automate routine tasks – and when not to. We had a cautionary tale of an elaborate automated doc toolchain that couldn’t be maintained after its creator left the company, nice distinctions between personal productivity hacks and automation for a larger group, and meditations on automation ROI. Here are some key takeaways:

Automate all you like if it’s just about your own work - whether it’s email routing rules, keyboard shortcuts, or any other professional task for which you’re solely responsible.
Think more carefully about ROI and usability if you want to automate shared work. By all means automate routine and time-consuming tasks (“barnacle scraping” as one writer put it). But the cost:benefit ratio might not be worth it when it comes to one-off tasks. (This goes for personal automation too.)
When considering an automation, consider not just the time and tedium saved, but also what it might take to make automation usable for more people. Make sure, too, that you’re not threatening someone’s job by taking away a manual process they’re committed to or depend on.
Remember that automation can help reduce errors, too.

Upcoming community events¶

November is a big-ticket month for the events! Not only do we have a cavalcade of meetups to share, but we also have two community events on the books.

Write the Docs Day Australia is happening in Melbourne on the 24th, and you can still snag a ticket here: https://www.writethedocs.org/conf/au/2017/

API The Docs is holding their second event in Amsterdam on December 4th, and their sign up is still open here: http://apithedocs.org/

Here’s the full line-up:

November 8 – Austin, TX, USA – Monthly meeting

November 8 – Cambridge, UK – Video creation as a topic-based content delivery method

November 9 – San Francisco, CA, USA – Workshop: Markdown - Share your experience!

November 9 – Salt Lake City, UT, USA – November meeting - User Research

November 9 – Munich, Germany – Show and Tell: Documentation Tools

November 14 – London, UK – Documentation at GDS: docs as code, user testing, and agile teams

November 15 - Seattle, WA, USA – Gitbook For President!

November 15 - Los Angeles, CA, USA – Happy Hour/Social Meetup

November 16 – Boston, MA, USA – Challenges in Large Doc Sets

November 24 – Melbourne, Australia – Write the Docs Day Australia: One-day mini-conference