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.
Two upcoming API documentation events this Thursday
There are a couple of events on API documentation happening this Thursday. First, I'm giving an STC webinar on best practices for REST API documentation at 11am PST. Also, Andrew Fuchs is also presenting on API documentation at a Write the Docs meetup in Redwood City at 6:30pm PST.
Is the only way to plug into a documentation CCMS through DITA/XML?
If you want to manage your content in a system and take advantage of more robust documentation management, it seems like your content needs to be in DITA or XML for the system to parse and process it. Almost no component content management systems handle anything like Markdown or other unstructured content. This requirement will likely always push large teams toward DITA/XML.
Three models for single source publishing — and challenges with each
When publishing different versions of content for different audiences, you can choose from among several single source publishing models: individual outputs, rights-based views, and dynamic filtering. Each option has challenges, however, and is not easy to pull off.
My YAML tutorial in the context of Jekyll
YAML is a format that is becoming a common way to store properties for configuring systems. I created a new tutorial on YAML that shows how mappings and lists work, and how you can use Jekyll and Liquid to parse through the YAML content.
The third API course from Peter Gruenbaum on Udemy
Peter Gruenbaum's third API documentation course is now available on Udemy. This course covers topics in API documentation outside of reference material, such as tutorials and overview sections. This course will expose you to the many different needs in API documentation, and is a course I recommend even though it is briefer than Peter's other courses.
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.
subscribe via RSS