If I am learning to write developer documentation, should GraphQL be on my radar? -- guest post by Casey Armstrong
GraphQL, a query language developed by Facebook, is an alternative to REST that is rising in popularity. Exactly how does GraphQL differ from REST, and what documentation strategies and conventions should you follow when documenting a GraphQL project? In this guest post, Casey Armstrong explores GraphQL — the query language, its use cases, its tools, what developers need from its docs, and whether GraphQL is worth learning. Overall, Casey argues that learning GraphQL is a great way to specialize and stand out as a technical writer, but the technology is not talked about in the tech comm/API writing community as much as it is in the developer community.
Recording of Tech Comm Trends Presentation (STC Puget Sound chapter)
I recently gave a presentation on technical communication trends to the STC Puget Sound Chapter in Seattle, Washington, on May 21, 2019. This is one of the better presentations on trends I've given and culminates a lot of research and other iterations on this topic during the past year. You can view a recording of the presentation, check out the slides, grab the audio file, and see other details here.
ClickHelp -- a flexible online platform for authoring and publishing technical documentation
Let's say you need to create and publish technical documentation. Maybe you have a team of distributed authors, and you need all the robustness of an advanced tech doc solution, but you don't want to create your own version from scratch. (I've argued in numerous posts that creating your own tools from scratch can require a lot of time and hidden expenses.) Enter ClickHelp. ClickHelp is a flexible, online help authoring solution that offers an impressive number of features, from context-sensitive help to built-in metrics, content re-use, PDF export, full-text search, password protection, full review cycles, readability analysis, and more. In this post, I'll provide brief descriptions and screenshots as we browse through the various features ClickHelp offers.
My documentation project plan template
In this post I share my documentation project plan template. This is designed for project managers to complete. Having all these details present helps you scope projects and recall all needed details if you have to de-prioritize the project for a while.
How to avoid inefficiencies even with context switching
When you switch focus from one project to another with higher priority, this context switching can lead to a lot of inefficiencies. However, if you take time to review or work on the de-prioritized projects even just a little each day, then according to the Forgetting Curve, you'll be more likely to retain the needed context. When you do fully switch back to the project, you won't have to start over.
Reader question: Am I specializing too much by limiting my focus to docs only?
A reader asks whether he should be focusing not only on writing good developer docs but also building out doc portals and marketing material — in other words, being more of a 'full-stack' technical writer. This question taps into the dilemma between being a specialist or generalist.
Crash course in API documentation -- a one-hour video
If you want a condensed, one-hour version of what I cover in my API documentation workshop, check out this crash-course video.
Reader question: Is it a red flag in the hiring process if they tell you that you'll be the only tech writer, with complete control over everything?
A reader wonders whether having complete control as the lone writer in a company is a red flag he should watch out for, based on his previous experience. I agree that it is.
Reader question: Recommended setup for docs-as-code tooling?
A reader asks for my recommended docs-as-code tooling setup. I said probably Hugo with Docsy and Netlify, or maybe a solution like Readthedocs.com or Readme.com.
Upcoming conference: The Tech Comm Roundup, by The Content Wrangler
Scott Abel has put together a new conference called Technical Documentation Roundup, held May 21-23, 2019, in Menlo Park, California. If you're interested in attending the conference, there's currently an opportunity to get two tickets for the price of one.
Season of Docs -- opportunities for both tech writers and open-source organizations to benefit from each other
When I was at the STC Summit last week, I was chatting with Sarah Maddox about Season of Docs. This is a program where technical writers looking to gain experience in the field can work with an open-source organization for a three-month timeframe on specific projects, building up both experience and a portfolio of sample docs. In turn, open-source organizations can benefit from having dedicated, enthusiastic technical writers creating much-needed documentation.
Technical writer position for Amazon Appstore team in Seattle or Irvine
We have an open position on our team for a technical writer in Seattle or Irvine. This position is more of a mid-level rather than a senior-level, and the person will be documenting details around the app submission process with the Amazon Appstore. Contact me if you're interested.
My slide links and presentation descriptions at the 2019 STC Summit
If you're attending the 2019 STC Summit in Denver and you want to attend my presentations, download my slides, or get other info, I've added details below.
The essence of technical writing, and my five stages of review for documentation
The essence of technical writing is in making a complex product work from beginning to end. In my doc process, I push content through five stages of review, but this first one, which includes my own review, is the most important.
First look at Document360 -- an authoring/publishing tool that satisfies both KB and tech pubs needs
Document360 is a new authoring and publishing tool that spans the needs of both support teams creating KB content and technical writers creating documentation. Document360 provides a good balance of features that will satisfy both audiences. Launched in July 2017, Document360 is already growing rapidly with a robust customer base. In this post, I'll show screenshots related to many of these features and talk about the need to bridge the gap between KB and tech doc content.