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.
Experimenting with a shorter post style
I'm going to focus on writing more pages than posts. Given how few people use RSS, the distinction between pages and posts is becoming trivial. It makes more sense to focus my efforts on a more substantial format.
Added native library API section to API doc course
I added a section to my API documentation course on native library API documentation. For technical writers, this is one of the most difficult areas to excel in without a programming background.
Upcoming "Ask Me Anything" (AMA) session
I'll be available September 17 for an AMA session where you can ask me any questions you want, and I'll try to answer them.
Swagger tutorial for REST API documentation
I updated the Swagger tutorial in my API doc course. If you'd like to learn more about Swagger, you can follow along here for step-by-step instruction.
Survey analyzing skill requirements in job postings
A grad student in tech comm needs your response to a short survey that examines responses to skill requirements in job postings. You can post your responses in comments.
How to avoid broken links when single sourcing
Identifying and preventing broken links in single sourcing scenarios is a challenge with almost every tool and platform in tech comm. It is especially challenging with static site generators. I'm trying to implement some validity checkers with my Jekyll project to make sure I don't end up with dead or orphan links.
Editing workflows and reviews through Github's pull requests
Pull requests are requests to merge edits from a branch back into the master. This workflow facilitates review of technical content on Github, but implementing it has some challenges. Namely, the reviewer would need to be familiar with code syntax, locations, and branching.
Comparing object-oriented design to content reuse
In a presentation to the STC Suncoast chapter, Mark Lewis compares object-oriented design to content re-use. It's an apt comparison that helps illustrate the parallels between programming and single sourcing.
How authorization works with APIs
Some common forms of authentication and authorization with APIs include Basic Auth, HMAC, and OAuth 2.0. In this post, I explain how these methods work. This material comes from other content I'm preparing about REST APIs.
What is a REST API?
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.
Proposals for 2016 *STC Silicon Valley Chapter* presentations now accepted
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.
My process for creating vector diagrams with Illustrator
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 released
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.
subscribe via RSS