Home »

Write the Docs Newsletter – August 2018¶

Hi everybody!

Kelly O. here with your late summer issue of the Write the Docs newsletter! After a nice leisurely few weeks, mid-summer, we are definitely getting back into the swing of things in here docsland. Team Newsletter’s back on the case. The Prague conference is sold out and will be upon us in less than 3 weeks. And happening as we speak is the first-ever Cincinnati Write the Docs + Open Help event!

After nine wonderful talks and a day of animated unconference sessions this weekend, the inaugural event is continuing with three days of documentation sprints. We’re so happy to have the opportunity to partner with Open Help and bring the community together for a slightly different style of event. Attendees have had the chance to learn from each other, contribute to some great open source projects, and, of course, enjoy each other’s company out in the real world.

Thanks and congratulations to all the folks who made the Cincinnati event come to life!! It’s so exciting to watch the Write the Docs ecosystem continue to grow and change! Speaking of changes, I have one more bit of business before we get to the stories…

Next month’s issue of the newsletter will be my last as editor. Since we started the newsletter just before the 2016 Prague conference, it’s been my privilege to work with our dedicated team of volunteers to put together these digests from the documentation community every month. I’m sharing all of this both to thank you all for reading over these last two years, but also to put out the call for a new editor! It’s a wonderful way to give back to the Write the Docs community and you couldn’t ask for a better group of folks to work alongside.

If you’d be interested in learning more, drop me an email at newsletter@writethedocs.org or ping me on Slack (@kobrien042) and I’ll be happy to chat!

In the meantime, let’s tune into some highlights from the hiatus!

Common misconceptions about documentation¶

Inspired by Emily January Petersen’s guest post on I’d Rather Be Writing, documentarians discussed some common misconceptions about our profession that they’ve personally experienced. As one person pointed out, we know that it takes more than being able to use a word processor or a text editor to be a documentarian…but what about everyone else?

Here are some of the unfortunately common misconceptions mentioned on Slack this month:

Anyone can write good docs.
No one reads the docs.
Documentation is fast and easy to produce.
Documentation doesn’t have any discernible business value.
Tech writers are just there to make docs pretty.
It’s not a role that earns much respect or recognition.

Having this conversation with a bunch of other documentarians meant there was no shortage of support and commiseration to be found. When it comes to showing other people the error of their ways, one practical suggestion was to lean on whatever analytics or reporting you have – and if you don’t have any, start collecting some. Another perhaps less serious suggestion was to just stop writing the docs for a month and see how things go then. ;)

The #career-advice channel is always full of sympathetic ears and practical advice for whatever professional frustrations you may encounter.

In the time of web-based applications, what is a page and what is a screen?¶

A classic question of word choice arose this month: What’s the difference between a page and a screen - and which term should be used when?

Initially, a few documentarians seemed agree that a “page” should refer to a webpage and a “screen” should refer to a software interface. However, with so many of us documenting web-based applications, that distinction quickly loses its clarity. The Microsoft Writing Style Guide was consulted, and the following guidance emerged:

“Use page or webpage to describe one of a collection of web documents that make up a website. Use page to refer to the page the reader is on or to a specific page, such as the home page or start page.” (source)
“It’s OK to use screen in instructions to describe what customers see on the screen or how they interact with it.” (source)

So…not totally definitive, and certainly still rooted in the time before applications were the web and the web was applications. Other distinctions that were entertained included “pages” for static content and “screens” for interactive interfaces. Or using “pages” for longer-form layouts that scroll, and “screens” for more compact UI patterns. There are other guidelines out there, to be sure, but ultimately, whatever decision you reach on when to use “page” and when to use “screen”, what’s most important is that you are consistent.

The Microsoft Writing Style Guide is available for free online! Check it out (here) the next time you have a terminology question… and then ask in #general for a second, third, and fourth opinion.

Static and sites and generators, oh my!¶

Many documentarians wrestle with the trials, tribulations, and occasional joys of producing docs with static site generators (SSGs). For anyone new to SSGs, they’re a type of publishing tool that takes documentation source files written using lightweight markup languages and processes them into web-ready HTML. A fairly lengthy conversation produced some excellent points to consider if you are thinking about adopting such a tool – or if you’re already wrestling with one. The contenders this time around were Sphinx, Hugo, and Gatsby. Here’s a summary of the main points:

For some folks, Sphinx’s dependence on reStructuredText for a full feature suite is a blocker, because developer contributors don’t want to move away from Markdown. Some dev teams, however, are willing to make the move - it depends on your team and on your content management needs.
Others prefer Hugo to Sphinx because it seems to be more widely adopted, offers a wider range of themes from which to choose, and is more easily extensible. Extending Sphinx or developing a custom theme for Sphinx deliverables relies on in-house Python knowledge.
Gatsby offers broader functionality because it is built on top of React/Node and GraphQL. Unlike other SSGs, including Sphinx, it can build content drawn from multiple sources. Setting up a Gatsby pipeline can require more coding than with other SSGs, but can provide more powerful functionality if that’s what you need.

This month’s conversation was by no means exhaustive or conclusive. There are so many different approaches to building an SSG publishing workflow, and a lot of enthusiasm and knowledge around the pros and cons of each. You can definitely expect to see more where this conversations came from.

Experimenting with different SSGs yourself? Pop over to #static-site-generator or see if there’s a dedicated channel for the particular SSG you’ve got your eye on.