I joined the LDS Church in 1991 and stayed an active member until January 2014. I held many leadership callings, served a mission, graduated from BYU, and worked in the Church’s IT department for 5 years. What led me astray after being so consistent and believing for so many years? First, I want to define my audience. I am aware that many of those who leave the LDS or Mormon Church write bitter why-I-left stories. These stories contrast with...
Check out this presentation by Brandon Philips at the 2013 Write the Docs conference. In the video, Philips argues for "single-page docs," which are entire help systems rendered on a single page. He says that for many technical information sets, like APIs, having all the functions, classes, etc. appear on the same page reduces "click insanity" and allows developers to more easily find what they're looking for. ">See the full list of 20...
I'm presenting to the Sacramento STC chapter on January 16, 2014. It's a similar presentation I've given to the Berkeley and Silicon Valley chapters. You can view past recordings, slides, and other resources here. Now that this is the third presentation, though, I have changed this presentation a bit. I'm really reworking the first point about information fragmentation. I sort of took a lot of heat at the Berkeley chapter for my preferen...
I used Grammarly's proofreading software because my eyes become blind to errors after I read through the same post several times. When you write documentation for programming code, such as APIs and SDKs, you become accustomed to writing and editing code comments. Code comments are explanatory text mixed with programming code to explain what's going on in the code. For example, here might be a code comment for a JavaScript function: </p> ...
A few weeks ago I gave a presentation to the STC Berkeley chapter on findability of help content. The recording is available here: Your browser does not support the audio element. Download MP3 (right-click, then Save Link As) For the slides, see Recording and slides for why users can't find answers in help. The link refers to the Silicon Valley chapter presentation of the same material -- the slides are the same, but the presentati...
One of the main challenges to embracing DITA is accepting the idea that tasks and concepts should be separated. However, despite the common assumption that concepts and tasks should live separately when you follow DITA, actually it's not the case. You can combine concepts and tasks in DITA's output through your ditamap. Additionally, you can even combine concepts and a single task in a "general task" dita topic. Tasks versus concepts Pret...
For about the past 6 months, I've been using Markdown syntax as a quick way to convert content to HTML and publish on Drupal, which is where we publish our help. But lately I've been feeling the pain of this process. Markdown is a lightweight markup somewhat like a wiki syntax. Any time I needed to do something more, like prepare a collection of more than 5+ files to publish at once, with cross-references between them, it's been a chore ...
January 25, 2014 Update: The API Workshop is totally full now. However, we may repeat it in the summer. Since moving to California, I've noticed there's a high demand for technical writer jobs involving API documentation, but there's not much in the way of instruction, resources, or other events that provide training with API documentation. When I mentioned this to some local STC chapter leaders, they encouraged me to find an API expert a...
As this is New Years time, I wanted to write about a goal that many make every year: the goal to lose weight. For technical writers and other IT professionals, staying fit and healthy can be a real challenge. We sit in desks and stare at computers all day, generally being as sedentary as can be. It's easy for our bodies to degenerate into unhealthy blobs. As a technical writer, physical activity is not the norm on the job. In fact, you ca...
Blogging makes short-form publishing (1,000 to 2,000 word articles) easy, but what if you want to go beyond that, writing long-form content with more substance? For example, what if you want to use a blog to write a book, or a series of essays focused on a particular topic? You could write longer posts, but longer posts don't work well online. Most people reading online tend to stay only several minutes on a page before clicking elsewhere...
Search engine optimization 1.0 How to Search Engine Optimize (SEO) Your Help Documentation 1.1 Introduction, frames, iframes, and tech comm tools (search engine optimization) 1.2 Single sourcing and duplicate content (search engine optimization) ...
A reader asks, I am a college student that is unsure of what I want to do when I "grow up." I previously thought that I wanted to work in human services, and although I still have the same drive to help those less fortunate I don't think that I want to make that my career. Besides raising a child and taking care of the house, which I think is a full-time job on its own, I also work outside of the home (I get to my school work some time be...
My Christmas wish list for Santa is now on techwhirl.com. You can read it at Dear Santa: Tom Johnson's Nearly Impossible Wish List. I'm not sure how practical it is, but I had a lot of fun making it. There are also quite a few wish lists from other tech comm people, such as Mark Baker, Kristina Halverson, Joann Hackos, Jack Molisani, and more. You can see the full list here.
Search engine optimization 1.0 How to Search Engine Optimize (SEO) Your Help Documentation 1.1 Introduction, frames, iframes, and tech comm tools (search engine optimization) 1.2 → Single sourcing and duplicate content (search engine optimization) ...
Search engine optimization 1.0 How to Search Engine Optimize (SEO) Your Help Documentation 1.1 → Introduction, frames, iframes, and tech comm tools (search engine optimization) 1.2 Single sourcing and duplicate content (search engine optimization) ...
