REST API documentation workshop recording (STC Sacramento)
I recently gave a workshop on REST API documentation to the STC Sacramento chapter. The workshop is about 3.5 hrs long and covers a lot of the concepts that I detail in my API doc course. In the workshop I first show you how to use a REST API like a developer. We then walk through common sections in API documentation, especially reference topics. Finally I give a tour of API documentation publishing tools.
Version 5.0 of my Documentation Theme for Jekyll now available
Version 5.0 of my Documentation Theme for Jekyll is now available. This version allows you to associate different sidebars for different products on the same site. I'm trying to move away from the separate outputs model to provide a more web-friendly and integrated doc site experience that facilitates navigation across products on the same site.
Hi there – Let’s get casual… Guest post by Lavanya Krishnamurthy
In this guest post, Lavanya Krishnamurthy explores the use of a casual tone in documentation as a way to give users a sense of having a conversation with the author. She presents several easy techniques for implementing a casual tone, and also notes the potential tradeoffs this approach can have.
Shannon got into Stanford's MA Liberal Arts program
Selling Girl Scout cookies
Starting a new series on visual communication
The other week on Twitter I noted that, despite the power visuals play in communicating technical concepts, there's not a lot of good information out there on visual communication in the context of technical documentation. As a result, I'm starting a series focused on visual communication, somewhat like the series I wrote about API documentation. One benefit of publishing this info on a blog is that I can regularly publish small articles and benefit from widespread feedback to help me course-correct early and move towards more accurate information.
10 minute podcast on API technical writing with Ryan Weber on Stitcher
Ryan Weber, the Director of Business and Technical Writing at the University of Alabama in Huntsville, has a podcast called 10 Minute Tech Comm. In this podcast, he records short interviews with technical writing practitioners and innovators covering a wide variety of topics. Recently Ryan interviewed me for a podcast on API technical writing.
Retrospective — Looking back at the good and bad of previous experiences
As I move into my new job, one goal I have is to learn from the experiences at my former job and improve this time around. I want to avoid repeating the same mistakes but also remember to build on those things that worked. This post is a retrospective look at the good and bad of previous experiences.
So People Don't RTFM? Write a FM That's Worth R'ing — Guest post by Marcia Riefer Johnston
The following is a guest post by Marcia Riefer Johnston exploring an alternative view towards the RTFM argument. In this post, Marcia argues that it's the writer's care and interest in the product and users that leads to producing help content worth reading versus content that is mechanical, dry, and lifeless.
Lightweight DITA article in Technical Communication Journal
A recent article in the Technical Communication Journal explores lightweight DITA and the way it removes some of the complexity from the authoring process. Lightweight DITA is still in development, but it holds great promise in simplifying DITA and allowing authors to connect into larger systems for managing doc content without abandoning HTML.
I'm starting a new job at Amazon Lab126
I'm starting a new job at Amazon Lab126 in Sunnyvale, California this week. This past week I closed out the remaining projects, tasks, and other final details at 41st Parameter / Experian in preparation for the transition. This week I'll be in Seattle (where Amazon's headquarters are located) all week for training.
Answering questions in James Gill's upcoming book, How to Get Started as a Technical Writer
James Gill is working on the second edition of his book, How to Get Started As a Technical Writer. I contributed a questionnaire for a section that explores a day in the life of a technical writer. In addition to describing common tasks I do as a technical writer, I explain how I got started in technical writing, what I like best about technical writing, challenges and difficulties I face as a technical writer, future directions for technical writing, and more.
What is the ideal tool for developer documentation environments?
When deciding on the right tool to use for developer documentation, you have to evaluate just how much developers will be contributing and interacting with the documentation. In some scenarios, it will make sense to use developer tooling for docs to support more developer involvement. In other scenarios, it may be better to simply give developers a space where they can do brain dumps of technical info, but then to have tech writers edit, rewrite, and transition the content into tech writer tooling in order to handle more robust requirements.
Updating from redcarpet and Pygments to Kramdown and Rouge on Github Pages
Github Pages is a sweet service that builds your Jekyll site for you when you commit changes to a Github repo. If you were using redcarpet and Pygments, you now should switch to Kramdown and Rouge to stay updated with the recommended Markdown filter and syntax highlighter supported by Github Pages. Switching to Kramdown requires you to both update your configuration file and usually use 3 spaces when inserting code blocks within list items instead of 4.
Why didn't WordPress take off with tech docs?
Despite the dominance of WordPress as a web publishing platform, which is used for nearly 75 million websites today, WordPress has rarely been used by technical writers as a platform for publishing technical documentation. Some of the reasons WordPress is avoided is due to its heavy LAMP stack architecture, lack of component content re-use, and inability to publish multiple outputs such as PDF.
subscribe via RSS