Moved my API doc site into separate repo
If you click the API Doc button on my primary navigation bar, it takes you here: idratherbewriting.com/learnapidoc/. Previously, there wasn’t a separating path called “learnapidoc.”
This doesn’t seem like much of a change, but behind the scenes there is quite a bit that’s different. First, I moved all the API doc content into its own repo here: learnapidoc. (My blog’s repo is here.)
Additionally, I used a different theme with the content. I actually developed this theme for a project at work (which we open sourced), but it doesn’t look like we’ll be using the theme after all.
This theme includes a search and a multilevel menu that doesn’t use an accordion toggle like my previous doc theme. I also added a breadcrumb that helps orient users. In the breadcrumb, “Home” takes you back to my blog.
I’m still fine-tuning the material. For example, I plan to add numbers back into the headers and provide next/previous buttons between each of the pages. However, for the time being, I haven’t included these features. Hard-coding numbers into the titles is a serious pain if you decide to switch around topics or insert new ones. I need to do this programmatically if I do it at all.
In moving content into another repo, I also realized something about GitHub. With GitHub, all your repos are accessible from subfolders off of your home domain. In my main repo, tomjoht.github.io, I have a CNAME that redirects tomjoht.github.io to idratherbewriting.com. When you add additional repos to your GitHub account, like learnapidoc, you could access the repo’s content by going to tomjoht.github.io/learnapidoc, but since your CNAME already redirects tomjoht.github.io to idratherbewriting.com, it does the same for the other repos. Now you access learnapidoc by going to [https://idratherbewriting.com/learnapidoc]. This is incredibly cool!
Having content in separate repos provides a number of advantages. Not only is having the content in its own repo easier to manage, you can also apply unique settings for themes and apply other workflows to the content.
In moving the URLs, I used the Jekyll redirect from plugin (which GitHub supports to create 301 redirects). I also used the URL Mapper function from Disqus to move my comment threads to the new URLs (though for some reason the comments on the homepage didn’t move yet).
Why did I move the content? Well, I haven’t even discussed this yet, but I’ve coded all the necessary files to output the content from this repo into MOBI for Kindle. I want to publish this content as an eBook, among other things.
I initially experimented with Gitbook for its EPUB output, but in my experiments, the EPUB output kind of sucks on Kindle. Some navigation controls are missing, formatting is a bit messed up, and overall I don’t like the loss of control. Plus, since I work for Amazon (but not in the Kindle division), I’d like to try generating my eBook using Kindlegen. I’m still fine tuning things here, so stay tuned for more updates to come.
I also plan to incorporate PDF generation from the site (using Prince XML), but I haven’t gotten around to that yet. In the end, I want to output the content as HTML, MOBI (Kindle), EPUB, and PDF.
My kids tell me no one will buy the eBook if they can get the information online for free, so I’ve been thinking of using Memberful to gate the web content with a paywall. However, I have mixed feelings about this for a number of reasons. Primarily, gated content isn’t discoverable, so I’d lose a lot of readers right off the bat.
Also, sites with paywalls are usually delivered over HTTPS (for security), but GitHub Pages only supports HTTPS if you don’t use a CNAME. (Remember, I use a CNAME to redirect tomjoht.github.io to idratherbewriting.com.) Even with just HTTP, though, I doubt my site would be subject to hacking attempts given that it’s entirely static (unlike database-driven CMS sites).
Finally, I probably make more off one advertiser than I would from any potential eBook sales. The traffic boost from the content is key for persuading advertisers to the site. That said, this API doc site now exists as a separate site with its own theme that lacks the sidebar banner ads, as do my other non-blog subsites in other repos. But I incorporated my newsletter signup on the API doc site, so I’ll redirect visitors back to my blog in the end.
I’m still fine-tuning the content and have a lot more work to do. Technology evolves daily, it seems, so things quickly slide out of date. For example, Swagger UI has come out with a new display that (thankfully) fixes some issues I noted previously. It’ll be at least another month of editing before I’m ready to kindle-ize my content.
Overall, I like the idea of putting effort into content that will eventually be published as an eBook. Blogging is fun, don’t get me wrong, but after posts slide off the homepage, they’re yesterday’s news. A blog post is extremely short-lived. After a few years, most people (and search engines) assume the content is out of date.
Instead of pouring so much energy into long-form blog posts, I’d like to pour that long-form effort into pages that will eventually form into a eBook. These pages will also be published online, so it probably won’t make that much of a difference if the content lives in a post or page. Some posts might function as early drafts that eventually get reworked into pages, and such.
In general, I think I’ll start treating blog posts more like their original intent: web logs, or journals (kind of like this one). A blog should chronicle your daily thoughts and efforts. I find that these kind of entries are more engaging anyway. Most of us already have the industry knowledge we need, but we read because we enjoy hearing another’s voice, following the person’s thoughts and activities as they try to achieve a goal. Blog posts should be entertaining and sometimes enlightening, but not necessarily hard-core instructive like a book.
I’m also coming to realize how bloggers differ from authors. People always tell me that they’ve “been following my blog for years.” When I hear this, I’m always surprised, because the person who makes the comment has usually never made a comment or even read my latest posts that week. But I’ve come to realize that there’s something about following a blogger online that’s different from reading a book author. To be a blogger really means to be a “web logger,” a journal writer, and people often connect with that content more intimately than they do content from a book. You build up relationships with readers over months and years of sharing your thoughts and experiences about a variety of topics.
I frequently look for good tech comm to read online, and I welcome these journal-type entries. When I need a break, or want to unwind, or just get a little bored, I’d like to read a good blog post. I don’t want to read something thick, drenched with thick research or how-to details and other information. I just want to read 500-1000 words of someone’s thoughts, speaking to me in a unique way. Something light but interesting. Something to make me smile before I return to the grind of whatever I’m documenting.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.