Write the Docs Newsletter – October 2017¶
Hello friends and fellow documentarians!
Kelly O. here, happy to be arriving in your inbox for another round-up of docs-wisdom gleaned from our community. It’s been a big month since last we spoke. We had our fourth European conference, we’ve surpassed 2500 members in Slack, AND it’s officially been a year since we started this here newsletter experiment. Happy newsletterversary!
We’re going into the last few months of this year with our sights set on shoring up some of our community frameworks, as well as developing some new projects (secret! exciting! forthcoming!). We’re so happy to have you all along for the ride!
Unsurprisingly, we had a bountiful harvest of interesting and useful conversations to choose from for this issue. We’ve tried to assemble a good mix here for your perusal. Have a great month!
Errata: In assembling the meetup calendar below, I suspect I did something wrong last month, to have come up with so few. If you ran a Write the Docs meetup last month that I didn’t catch in the newsletter, I’m so sorry!
Putting our URLs to work – for us and our readers¶
How do we make our URLs meaningful to our readers? What should we do when content inevitably moves (or is removed)? How can we make sure all of the great content we write remains discoverable?
When discussing these questions this month, the community started from a point of agreement: good URL paths should carry meaning. For example, a lot of doc sites have URLs that reflect their content hierarchy, like site/category/article-title. Ideally, in such situations, if a reader truncates the path to site/category/ they should find a list of every article in the category. But content restructuring and obsolescence are facts of life for most documentarians. It’s unrealistic to think that Cool URIs don’t change. When the inevitable does happen, it’s important to make it as easy as possible for readers to find new locations. That means redirects!
Creating redirects can be difficult to manage when there are lots of external links or when lots of URLs are changing. Sadly, most documentation tools – with the notable exception of MindTouch – don’t offer automated redirects. One suggested approach was to use analytics to prioritize your most critical URLs, setting up manual redirects for those pages first to keep your content discoverable. For long term URL hygiene, folks suggested automated link-checking tools to track down and update broken links and stray pages.
The true meaning of “API”¶
What exactly are we referring to when we say “API”? While the initialism itself stands for Application Programming Interface, it’s a more complicated question than it seems. When it came up this month, it sparked a lively conversation that suggested that API might mean different things to different people in different contexts.
Most of the conversation revolved around that idea that when we say “API”, we assume that our reader (or listener) will inherently understand the type of API we’re talking about. But that might not be the case as often as you think. If you work with REST APIs, it’s likely you’ll assume that API has a silent “REST” in front of it. But if you’ve spent your career working with library APIs, that will probably be the meaning you default to.
There was some question of whether any of this mattered. Whether it’s a library, REST, SOAP, or other type of API, they’re all still “methods of communication between various software components” (thank you wikipedia). But as evidenced by the length and depth of the conversation, it’s definitely a topic worth clarifying. Handily enough, one of our Prague speakers, Garen Torikian, has a slide on this very topic in his presentation, ” Trustworthy and Sensible API Documentation with GraphQL.”
In the meantime, check out #documenting-apis or #apithedocs for more conversations about APIs!
Proofreading and copyediting your own work¶
If you’re a lone writer, you’ve probably been in the unenviable position of not having an editor around to proofread, copyedit, or otherwise sanity-check your writing. It’s a perennial dilemma, and one that surfaces regularly on Slack. This month produced a particularly good batch of suggestions and resources. To help you clean up your copy when your only editor is you, here’s some tips and tricks from the Write the Docs hivemind:
- Put your writing away and review it at least a day later.
- Print it out on paper and read/edit in the new format.
- Read each sentence independently. Try reversing the order of sentences, starting with the last one and working your way backward to the first. Or reverse the order of paragraphs.
- Listen to your writing being read aloud, either by you or by a device. Text-to-Speech tools are widely available.
- For typos, repeats, and especially homophones, highlight a single line at a time. If it’s hardcopy, use a ruler. This keeps you from reading to the next line and helps you notice the “the the” problems.
- Make the text much larger, or change the font. Folks recommended these tricks for on-screen or printed page reviews.
- Last but not least, check out this blog post of 10 tips for proofreading your own work. The post repeats some of our group’s suggestions, and adds more.
Defining developer relations/evangelism/advocacy¶
This month, someone asked a question which many of us have wondered about, at one point or another: “What does a developer advocate or evangelist actually do?” (You may have even wondered this _as_ a developer advocate/evangelist…)
The ensuing conversation made it clear that whether you call it developer relations (DevRel), developer evangelism, or developer advocacy, it can mean a lot of different things. But some common themes emerged:
- Folks in these roles are generally expected to be the “face” of their developer community. Their work involves making their product/language/framework/etc. more visible and more approachable.
- Often they sit at an overlap point between engineering – since they’re (ideally) experts in the tool they’re representing – and sales, marketing, documentation, etc.
- The line between “evangelist” and “advocate” gets blurry. Often, though, the evangelist side is about bringing the product out to the community, while the advocate side focuses on bringing the community’s voice back to the product team.
- Although these roles may have gotten their start in the open source community, they’re becoming increasingly common across the industry.
For further reading on the topic, this Medium post has lots of good thoghts: https://medium.com/google-developers/the-core-competencies-of-developer-relations-f3e1c04c0f5b
Upcoming community events¶
WRITE THE DOCS DAY AUSTRALIA COUNTDOWN: Six Weeks Left! We’re so excited to be coming up on our first official Australian event! If you’re going to be in the Melbourne area in November, come out for a full day of sprints, talks, and community-building! Check it out (and get your ticket!) here: https://www.writethedocs.org/conf/au/2017/
- Tomorrow! October 10 – Portland, OR, USA – Confluence Docs With Node.js, Intro to the PSU Tech Writing Program
- Also Tomorrow! October 10 – Seattle, WA, USA – WTD Seattle October Meetup
- October 11 – Brisbane, QLD, Australia – Peanuts and Minimalism and Technical Writing
- October 12 – Leeds, UK – Social: First Meetup
- October 12 – San Francisco, CA, USA – Lightning Talks!
- October 14 – Fredericton, NB, Canada – Technical Communicator Lunch Social
- October 17 – London, UK – Worked Examples in the Documentation of Complex Systems
- October 24 – Boston, MA, USA – mabl Happy Hour + Lightning Talks
- October 25 – Austin, TX, USA – Content strategy for your docs
