REST APIs use HTTP protocol (or rather, the web) to transport the request and response messages between clients and servers. The client and server can run on any language or platform as long as the request/response is sent via HTTP. To understand REST APIs, it helps to compare them with their predecessor: SOAP APIs. Both SOAP and REST APIs are a kind of web service.
If you would like to present to the Silicon Valley STC Chapter (located in Santa Clara, Calif.), you can submit a proposal to speak. Chapter meetings are held on Monday evenings once a month and last about an hour. We're inviting proposals this year to give more people a chance to speak. Speaking at a chapter event can build credibility for a Summit proposal as well.
This past week I was creating some diagrams for a project, and I feel like I've settled into a good workflow for creating high quality diagrams. Here's my process: Create the file in Illustrator, store numerous diagrams on artboards in the same file, save as SVG with outlines, and embed like an image but specifying the max-width.
Version 3.0 of my Documentation theme for Jekyll is now available. This theme has a ton of features, such as tags, series, collections, search, PDF generation, and more. Additionally, I've written up detailed documentation for using the theme. Overall, the theme shows how to do single sourcing (including both web and print output) as well as conditional filtering of content based on different attributes.
To excel in a startup environment, technical writers need to have a strong technical aptitude, the ability to both lead and be independent, the capacity to evaluate content strategy decisions instead of just documentation, versatility to write in a variety of situations, and stability to weather the roller-coaster ride of startup finances.
In this podcast, I talk with Lisa Meloncon, an associate professor at the University of Cincinnatti, about the academic-practitioner divide.
Although the work of practitioners and academics should inform each other in mutually beneficial ways, these groups tend to be somewhat isolated and separate. Some reasons for the divide include lack of focus on tools, paywalls set up with publications, and the topics in journal articles.
It's hard to make wikis successful because the wiki platform doesn't instill contributors with a sense of ownership with the content they create. As a result, wikis often become full of redundant, outdated, and trivial content. I'll share my lessons learned with wikis during a roundtable discussion with the North Bay Communicators group on August 11.
I've added a Zip Recruiter job feature on my site to help you more easily find jobs in your area.
Bob Watson recently finished a PhD with research that examined how the design and content of API reference docs affects the user's performance. In this podcast, I talk with Bob about his findings and his other research interests, primarily around goal testing to measure documentation's effectiveness.
Learningdita.com is a free online educational resource created by Scriptorium for learning DITA. The initial course on their site, "Introduction to DITA," lasts about an hour and will introduce you to core DITA concepts and techniques.
Sometimes with developer documentation, some of the content may be beyond your skill level to set up and test. In these cases, you can ask developers for help in setting up your system so that you can run the necessary tests. Alternatively, you can test the instructions with users and gather feedback indirectly.
When you test a product, you usually put together simple test scenarios that include actual values and other specific details. You can repackage these test scenarios into documentation-based tutorials that help users understand how to use the product. By including specific values and instruction with a defined end, new users can better understand how to use the product for different use cases and scenarios.
If you want to learn how to document REST APIs, consider taking Peter Gruenbaum's courses on Udemy. He recently released part 2 of his REST API tech writing course. Part 2 gets into the meat of writing reference documentation for REST APIs.
Here are the survey results from my survey I conducted about a possible REST API workshop. Although a workshop would have a lot of appeal, many people are interested in online options since they aren't located in the area where I would give the workshop.
