Upcoming REST API documentation workshop in Sacramento
I'm giving an API documentation workshop in Sacramento on March 19, 2016, from 10am to 2pm. The cost is $25, and the event will be held at the Rocklin Public Library. The workshop will focus on how to write documentation for REST APIs, and will cover topics such as documenting endpoints, parameters, sample requests, sample responses, status codes, error codes, and more. You'll get some exposure to Postman and cURL as well.
New section in API documentation course: The Job Market for API technical Writers
I added a new section to my API documentation course called The Job Market for API technical Writers. In this section, I try to elaborate on why knowledge of programming is often listed as a requirement in API documentation jobs, even if you're mainly documenting a REST API.
Challenges in documenting long JSON objects
Documenting long JSON objects (with hundreds of lines of code and multiple levels of nesting) can be challenging. There are different approaches to take, but none of the approaches seems to work well. I updated my API doc course topic with a section comparing the various approaches.
How to apply agile processes to manage your life's projects
The same scrum approaches used to manage software development projects can also be used to manage projects in your own personal life. If you follow the core scrum principles, you might actually be able to get "twice as much done in half the time," as Jeff Sutherland, co-founder of agile, promises.
The problem with adopting bleeding-edge tools
The problem with adopting bleeding-edge tools is that they usually handle only the simplest use cases. When you try to make these bleeding-edge tools handle complex publishing requirements, the simple tools transform into Rube Goldberg machines of sorts. Since engineers usually don't have to solve these complex publishing requirements themselves, they tend to embrace the simple bleeding-edge tools and can't understand why anyone would pursue a more complex route.
Spec-driven Development with RAML -- presentation by Michael Stowe to STC Silicon Valley chapter
In October 2015 Michael Stowe presented to the STC Silicon Valley chapter about spec-driven development, with a demo of RAML, which is an API specification similar to Swagger. Pretty much everyone who attended his presentation was impressed at how cool RAML is in making API documentation interactive. You can view Michael's slides and listen to the spec-driven development presentation recording here.
First video for API documentation course -- your feedback?
This is the first video I recorded for my API documentation course. Since it's the first course video, I want to make sure my approach works well for later videos, so any feedback you have about it would be helpful. For example, you might comment on the lighting, background, length, on-screen text, my delivery, the audio or video quality, and other details.
Are technical writing blogs growing or dying?
To assess whether blogs are growing or dying, I quickly compared metrics for the past 7 years on my blog, looking at the number of sessions per year. I then correlated the sessions with the number of posts that year and the cumulative number of posts on the blog overall. It seems that my blog readership is on a slight decline. This is likely due to the proliferation of online sites, not of blogging in general.
What is the technical writer's role in content marketing?
Technical writers should repurpose their information-rich content into content marketing deliverables that can be used to build relationships with potential audiences in the market. This content can help establish thought leadership, visibility, and trust with your audience so that when you start releasing and mentioning your 1.0 product, your audience adopts it.
Analyzing top posts on my blog during 2015 — Deciding between brand versus readership
The main traffic on my site comes from new technical writers looking for general information about technical writing careers. To increase my readership, I would probably need to post more general information about technical writing (salaries, programs, skills, tools, etc.). But this kind of focus may take away from my brand or sense of expertise about more specialized topics. The topics you write about brand yourself as an expert in those topics, and ultimately you have to weigh what matters most to you.
My 2016 technical writing trends and predictions, or the ripple effects of API growth on technical writers
In 2016, the continued growth of APIs will create a ripple effect across the technical writing community that involves a variety of changes. Some of these changes include an increased adoption of Swagger, Markdown, revision control, learning programming, authentication solutions, Write the Docs meetups, new authoring tools, tutorials, API-based CMSs, and more.
Recording of Creating Documentation for Startups: Panel Discussion -- Write the Docs San Francisco
The following is a recording of a panel discussion at a Write the Docs San Francisco meetup held Dec 17, 2015. The topic is on creating documentation for startups.
My upcoming 2016 STC Summit workshop and presentation
I'm going to be giving a workshop on API documentation and a presentation about Jekyll at the STC Summit in Anaheim, California in May.
How do you stay updated with changes developers are silently making?
You can stay updated with what developers are working on by analyzing the items assigned to the current sprint and asking the assigned developer for details.
Those pesky authoring tool questions, and an update on my adventures with Jekyll
At the last WTD meetup, someone wanted to know my current thoughts on using Jekyll. Is it still what I recommend? There are challenges with search, file directory fragmentation, and authentication, but only the first point is inherent with static site generators.