How to deliver newsletters for your Jekyll site
Although email may seem somewhat antiquated, it has by far the greatest reach of any online communication method. If you have a Jekyll-based site, here's an easy approach to sending out an email newsletter. This approach involves using a for loop to get a summary of your latest posts and then pushing the content into simple HTML formatting that you can paste into Tinyletter's email template.
Coding the sidebar navigation element for documentation websites
Sidebar navigation is one of the more complex components of a documentation site, and it is critical for helping users understand and find documentation. I hacked together a sidebar menu for a doc site that's hosted on a somewhat inflexible platform, using Jekyll to generate the sidebar. Important features of a documentation sidebar include multiple levels of depth, expand/collapse options, accordion effects, fixed navigation, dynamic menu highlighting, and more.
From podcasts to audio books and now back to podcasts -- experimenting with a new angle
Lately I've been turning my attention away from audio fiction and back into technology podcasts. I'm curious whether looking at the tech comm angle associated with technology news might provide a fruitful angle for blog posts and discussion.
Saving Your Sanity Through Better Client Relations -- with Alisa Bonsignore
In this presentation, Alisa Bonsignore, a technical communication consultant based in the San Francisco Bay area, talks about how she developed confidence and experience in consulting with clients about writing projects. In the beginning, Alisa started out by apologizing for projects in which she worked excessive numbers of hours for little pay, often trying to meet last-minute requests that required late nights and zapped her work-family balance. But project by project, she started to understand how to interact with clients in a more professional, self-respecting way. Ultimately this helped save her sanity and build a stable income through a reputable business.
My gravity towards tools
Tools are an odd problem in tech comm. On the one hand, companies don't want you to spend hardly any time at all either learning or setting up authoring tools. Preferably, you should already be familiar with the company's tools before being hired. Then after you're hired, companies usually want you to focus on content, not any kind of tool configuration or setup. On the other hand, it seems like almost every company I've been at has needed extensive help with authoring/publishing tool setup and configuration. I am starting to think that my pattern of deep diving into tool sets at companies is indicative of a deeper interest in web development.
Zooming out and in with navigation
Kanban may be a better fit than scrum when you support large numbers of engineers
Since I've been working at Amazon, my tech comm role has shifted more to content curator and publisher than simply author. This shift in roles brings with it some new challenges and responsibilities. Some of the previous scrum methods with agile no longer seem to fit. I'm finding that kanban might align better with my workflow.
How can technical writers thrive in agile environments? Event recording and details
Last Monday we had a record turnout at our STC Silicon Valley chapter (with about 40 attendees). The topic was a panel discussion on how to thrive in agile environments as a technical writer. With 5 panelists all from different companies, the perspectives and practices they shared varied a bit, which showed the adaptations different writers and companies have made with agile to make the process work for them. This post contains a full description and recording of the event.
Implementing Swagger in your API documentation -- My ISTC article
I recently published an article about Swagger in the Autumn 2016 edition of ISTC's magazine, Communicator. ISTC stands for Institute of Scientific and Technical Communicators. My article provides an introduction to using Swagger (now called OpenAPI specification) for publishing your REST API documentation.
Recording of Let's Tell a Story -- Scenario-Based Documentation, by Matt Ness (STC Silicon Valley Presentation)
Matt Ness, a technical writer at Splunk and a co-organizer for WTD San Francisco, recently gave a presentation to the STC Silicon Valley chapter called Let's Tell a Story: Scenario-Based Documentation. In this presentation, Matt talks about ways to integrate storytelling techniques into documentation, drawing upon his experience as a Dungeons and Dragons player and his player experience from other video game or fantasy worlds. To help users on their journeys and quests, you need a narrative to guide them and a manual to help them overcome obstacles. Video, slides, and audio from the presentation are included in this post.
Balancing the never-ending list of documentation to write with your natural interests and passions
Sometimes I think that I've covered every possible topic on this blog that is possible to write about, and my muse becomes silent for a while. But then I remember the purpose of the blog -- to be a web-based log, or journal -- and I realize that the only reason I wouldn't have anything to write about is if I stopped having experiences, stopped reflecting on those experiences, and ultimately became a zombie. That zombie state is the death of any career.
The variety of tools tech comm professionals use
Ferry Vermeulen asked more than 70 tech comm pros -- from both the U.S and Europe -- what their 3 essential tools are. The combination of American and European responses makes for an interesting mix. While the majority of respondents listed either MadCap or XML tools, people also listed a variety of tools for working with images, prototypes, projects, and more. There were more than a dozen tools I'd never heard of. In this post, I highlighted some of the lesser known tools and also the responses that caught my attention as being unique, insightful, or otherwise interesting. Overall, it's fun to look through the profiles and see the diversity of people, tools, and specializations in the tech comm field.
Presentation recording: Hunting for API developer documentation jobs in the San Francisco Bay area, by Andrew Davis
Andrew Davis recently gave a presentation on finding developer documentation jobs (mostly for API documentation) in the San Francisco Bay area. The title of the presentation is Hunting for Dev Doc Work around the Bay. You can listen to the presentation recording, check out the slides, or just download the audio.
The complexities of translation and the need for dynamic variables in the build process
Translation is a complex undertaking that usually requires you to take advantage of dynamic variables and other parameters in your source format in order to generate out different languages. Although most people think of static site generators as containing static content only, it's actually only static output. During the build process, you can take advantage of these more dynamic characteristics to handle rules for outputting to different languages. In this post, I explain some of the details you have to account for (includes, links, images, re-used content, etc.) when managing a translation project using a static site generator such as Jekyll.
Will the docs-as-code approach scale? Responding to comments on my Review of Modern Technical Writing
My previous post reviewing Andrew Etter's ebook on Modern Technical Writing got an enormous response. Some readers said the docs-as-code approach works only for small shops and doesn't scale to large projects. They said content re-use and translation also become problematic. However, perhaps the real differentiator shouldn't be product size as much as product category. The docs-as-code approach (which is what I'm calling it) works particularly well for developer documentation, such as API documentation, which usually doesn't contain the same challenges that component content management systems (or CCMSs) were meant to solve.
subscribe via RSS