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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
You can watch the recording of Richard Mateosian's November 2015 presentation to the STC Silicon Valley about version control, writers, and workflows.
Using Jekyll for documentation will probably require more time and effort than a commercial out-of-the-box authoring tool. On the other hand, Jekyll may be more suitable to you if you're customizing a doc website, want a developer's workflow, or simply want the freedom of using open source tools and working in code.
Swagger should be a feature of every REST API doc set, since it connects with the user's primary desire to try out a product in order to learn it.
As I've been configuring the Swagger spec file and UI for one of the APIs I document, I had a few realizations that I wanted to share. Some realizations involve understanding the Model versus Model Schema part of the Swagger UI, the syntax of using JSON references within the spec, how validation works, and more.
In this guest post, Robert Desprez looks at the possibility that advanced technology may replace the need for technical writers. Desprez explores a recent book by Martin Ford (Rise of the Robots) on the subject.
