Here are the slides from my workshop on REST API documentation. I have two sets of slides:
For detailed notes, see Documenting REST APIs.
For detailed notes, see Publishing API documentation.
I also gave a presentation that was a shorter version of the Publishing APIs slidedeck:
This presentation was recorded as part of the virtual track.
Overall, I think the workshop went well, but I do have some thoughts on improving it next time:
Also, wifi was problematic, as it usually is. People could connect to wifi but not go online. We had to have a hotel wifi tech come down and sort things out.
Here’s what I thought worked well:
I also gave a 45 minute presentation that was also part of the virtual track. I thought this presentation went well. Later someone said they wished they could just see an API. In retrospect, I think I should have demo’d a bit more how some of these API publishing platforms work.
Because I was in the virtual track, I had to submit my presentation ahead of time and use a dedicated computer running Adobe Connect. I could have browsed online during the presentation, but I would’ve had to use the screen-sharing options inside of Adobe Connect and also sign into various sites.
The next time I present this information, though, I’ll probably show the demos. Because really, the demos that I have prepared are pretty good. I took the same API information from a simple Mashape Weather API and published it across at least 5 different platforms (Github, Apiary, Swagger, Jekyll, and readme.io). Again, detailed notes are here: Publishing API docs.
I made a good decision and bad decision in making flight/hotel plans. The good decision was to stay at an off-site hotel next to a Bikeshare station. Why stay off site? I really dislike fancy hotels – they all look the same and insulate you from the real city. Usually wifi and breakfast cost extra, and why pay so much if you’re only crashing there at night?
For a third of the price, I stayed at a nearby German Village Inn two miles away. The Summit staffers don’t really like people staying in off-site hotels, but no one requires you to stay at the conference hotel. If a city has a bikeshare, it makes it super easy to get around. There was a bikeshare station both next to my hotel and next to the conference hotel. Since I’m accustomed to riding my bike everywhere already, this turned out to be ideal.
My bad decision was in taking a red-eye flight to get to Ohio. First of all, getting to Ohio sucks. You have to take connecting flights because nothing is direct. I thought I could lessen the time away from my family by taking the redeye flight and sleeping on the plane, but it’s hard to sleep sitting straight-upright on a plane, with no neck support. I only slept maybe 3 hrs. I never entirely recovered and was tired for a lot of the conference.
Throughout the conference I was thinking about how to convert my workshop notes into an online course. Although many of the tutorials are things I can record and talk through using conventional video tutorial methods, I do have some conceptual sections that don’t involve me clicking buttons or adding code on a screen.
For these conceptual sections, I want to try to record a “talking head” section in a video, as they’re called. I’m still undecided about the level of fidelity for the talking head sections. On the high end, I could set up a green screen with lighting and use an iPad teleprompter. On the low end, I could just put the camera on a tripod outside and wing-it from a few bullet points.
I probably don’t have that many conceptual sections to explain, so mostly likely I’ll do the latter. I think it’s better to show an illustration while explaining a concept anyway. Still, I do have an iPad, and the teleprompter method might be fun to experiment with.
Now that I’ve finished a season of presentations and workshops, I have more time on my hands. And I want to develop some new skills.
Overall, I enjoyed talking and interacting with people. Here are a few conversation snippets:
I know a lot of people, and a lot of people seem to want to talk to me.
Being a blogger and podcaster makes me extremely visible at tech comm conferences. It also amazes me what bonds form after you record a podcast with someone. It’s something that people remember even years afterward and still feel connected to you. It made me think, I should do more podcasts. And I will.
This Summit was the first time ever featuring an API track. I’m glad Chris Hester, the conference organizer, was aware enough with trends to recognize the interest and importance of API documentation. There were about 7 sessions related to API documentation, in addition to my pre-conference workshop on the topic.
In some of these sessions, newbies to API documentation required the discussions to remain at the introductory level. But during other sessions, we really jumped ahead and dove into more depth, such as during the Swagger presentation.
New this year, there was a pre-conference presentation coaching option and an on-site speaker ready room. I took advantage of both services and really got some good feedback.
Chris and another person actually gave me feedback on some other API doc presentations I’d given, and suggested ways to improve it. They said participants want to go through the actions of doing something (such as documenting an API). This helped me develop the thematic arc I used in my workshop.
In the speaker-ready room, I realized that white text on a black background doesn’t stand out very well, so I changed my template.
In attending the conference, one question I had was how to provide authentication for my documentation (I usually try to go to conferences with a few questions in mind). Our users have to log in to access content, and our current way of providing authentication (we upload content into site.com and use Salesforce to provide the authentication) isn’t ideal.
I did encounter one new vendor that looked pretty cool: Titania Software. It’s a content delivery platform that allows you to publish all of your outputs to customers in a convenient doc portal. Titania can sync with another repository, require users to log in, and even allow users to comment. It provides a comprehensive documentation portal for your content, complete with faceted filtering, search, and other features.
What’s also neat is that your files don’t need to be in XML or DITA to integrate with the system. They can be HTML, PDF, Word, or other formats.
The only drawback is the cost. This solution is probably $10k to implement and at least $30k per year, which isn’t bad if you’re a large enterprise with a lot of content. But if you’re a small doc shop, it may be harder to get budget for this.
I attended the Northeast Ohio outing to a triple AAA baseball game. I enjoyed chatting with my game buddies, but I have to admit that, even though I’m a sports enthusiast, I find baseball boring. And Ohio is humid and muggy, but clean and pleasant.
Ohio State University and other colleges have a huge student population in the area. I walked past some bars and clubs and saw a lot of college students, I assumed. But later someone just told me no, I’m just getting older so everyone looks young.
Get new posts delivered straight to your inbox.
I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.