My pros and cons of using Jekyll for documentation
As with any help system, there are some pros and cons with using Jekyll for documentation sites. Since I usually emphasize the pros of Jekyll in my posts, I wanted to balance out the perspective a bit by listing 10 cons and 10 pros.
Can you replace a CCMS with version control such as Git or Mercurial?
Instead of resorting to an expensive Component Content Management System (CCMS) to facilitate content re-use and collaboration across projects, you can probably get by with some basic version control tools that software developers have been using to collaborate on projects for years.
Tell me about your career as a technical writer...
Technical writing is a pretty awesome career. You'll probably enjoy it unless you dislike writing, aren't technical, hate working in team environments, and prefer to write content that pressures people to buy crap they don't need.
Why incremental regeneration in Jekyll 3.0 is such a big deal
Jekyll's incremental regeneration continuously rebuilds your project each time you save a change. This can help you quickly identify errors and fix them immediately, since the time between when you make the error and when you're notified of the broken build is reduced.
Increase efficiency 24 times faster when fixing errors — implications for technical writers on agile teams
If you want to influence developers to make changes to code (such as with UI text), it's 24 times easier for developers to make the changes if you tell them the same day they code the feature than if you wait a few weeks later. This means technical writers should keep pace with the features coded during each sprint.
Podcast: Spec-driven Development of REST APIs, with a focus on RAML -- interview with Michael Stowe
Spec-driven development is an approach to developing REST APIs by first describing and prototyping the API through a specification file (such as RAML or Swagger), and then coding the API. The spec not only serves as a contract for the API's development, it can also generate interaction documentation, unit tests, client SDKs, and provide other benefits.
Udemy podcast (with me) and infographic on technical writing
Recently I was interviewed by Alex Bankoff from Udemy for a podcast on the field of technical writing. The Udemy team also created an infographic about the topics covered in the podcast.
5 REST API resources to add to your reading list
The following is a collection of 5 worthwhile REST API resources (blogs, newsletters, or other tutorials) to add to your API reading list.
Tutorial for creating interactive consoles with RAML
This is a tutorial for creating interactive consoles with the RAML spec. The interactive console allows users to try out your API directly in the documentation.
Question: If you weren't a technical writer, what would you be?
My alternative to doing technical writing would be to do web design. I'd also like to use my creative talents to finish an API documentation course, among other efforts.
Why so little focus on API doc at tech comm conferences?
Although API documentation seems to be a rising trend, not many sessions at tech comm conferences focus on API documentation. This puzzles me and makes me wonder whether API doc is a sub-specialization of tech comm only popular in the Bay area.
Question: Can I earn a living blogging?
Although you can't earn much direct revenue from blogging, writing a professional blog can be brand you as an expert in a specific field. This can open doors for you professionally.
Question: How long has your API doc course been available?
I'm developing an online course for documenting REST APIs. I'm not quite done, and I'm trying to figure out the best freemium delivery model.
Question: How are you publishing and delivering your docs?
I'm publishing my documentation through Jekyll, delivering the content on internal servers for internal customers, and delivering it on Salesforce.com for external customers. I wish I had a better delivery mechanism externally other than Salesforce, but authentication solutions are either complicated or costly.
Question: How do I tell what platform people are using for API docs?
It's difficult to tell what platform someone is using for docs, but static site generators are pretty common. Other branding is sometimes easy to recognize.
subscribe via RSS