--- title: "I’d Rather Be Writing blog" description: "{% for post in paginator.posts %} {{ post.title }} {{ post.date | date:" canonical_url: https://idratherbewriting.com/page68/index.html --- > For AI agents: a documentation index is available at https://idratherbewriting.com/llms.txt. Markdown versions of all pages are available by appending .md to any page URL. # I’d Rather Be Writing blog [How can we know something that is totally unfamiliar to us?](https://idratherbewriting.com/2014/02/20/how-can-we-know-something-that-is-totally-unfamiliar-to-us/) Feb 20, 2014 • [technical-writing](https://idratherbewriting.com/category-technical-writing) I've been reading some science books lately and visiting a few museums. These experiences have led me to the following question: How can we know something that is totally unfamiliar to us, such that we've never experienced or conceptualized it in the least degree before? This question is more philosophical than practical, but it does play a part in our role as technical writers. To consider the whole scenario of the unknown, think of some... [An argument for complexity rather than simplicity in technical communication](https://idratherbewriting.com/2014/02/07/an-argument-for-complexity-rather-than-simplicity-in-technical-communication/) Feb 7, 2014 • [technical-writing](https://idratherbewriting.com/category-technical-writing) I am rarely impressed by mission statements, but I find the first paragraph of the recent reformulation of STC's mission statement refreshing. It defines the practice of technical communication as "the discipline of transforming complex information into usable content for products, processes, and services" (President's Midterm Report). The mission statement does continue on to address other less interesting topics, but that's beyond my co... [Gamification and user engagement in e-learning and documentation](https://idratherbewriting.com/2014/02/04/gamification-and-user-engagement-in-e-learning-and-documentation/) Feb 4, 2014 • [technical-writing](https://idratherbewriting.com/category-technical-writing) For the past year I've been working at a gamification startup company called Badgeville in Silicon Valley. Badgeville is one of a handful of companies specializing in “gamification.” When you gamify an application, you integrate game elements into non-game contexts to better engage your users. If done right, gamifying an application can increase the engagement of your users by up to 48%, compared to only 28% for those who don't use gamifi... [Will structure and style make documentation processes less costly?](https://idratherbewriting.com/2014/01/26/will-structure-and-style-make-documentation-processes-less-costly/) Jan 26, 2014 • [technical-writing](https://idratherbewriting.com/category-technical-writing) A reader writes, Let me start by saying that I am a huge fan! I've been following your blog for many years and together with Mark Baker's and Scriptorium blogs, you've taught me 90% of everything I know about tech comm and documentation. The problem at hand: Documentation for our biggest product has grown enormous over the years. The growth was organic, as more and more features and complexity was added. Our online help for the product cu... [Growing trends for APIs and my favorite resources to learn technical information](https://idratherbewriting.com/2014/01/20/growing-trends-for-apis-and-my-favorite-resources-to-learn-technical-information/) Jan 20, 2014 • [api-doc](https://idratherbewriting.com/category-api-doc) While riding home on the train today, I was thinking about directions I want to take my career. I actually don't have any presentations pending, no expected slides or research due (other than an article on gamification). As I thought about it, I realized that I want to dive more deeply into API documentation. The response to the API Workshop I'm helping organize has been really encouraging. Already we have 45 people signed up (with a cap ... [Upcoming interviews at the Intelligent Content Conference](https://idratherbewriting.com/2014/01/16/upcoming-interviews-at-the-intellent-content-conference/) Jan 16, 2014 • [technical-writing](https://idratherbewriting.com/category-technical-writing) Several years ago, at the STC Summit in Dallas, I took my video camera along and recorded about a dozen different interviews with presenters and other interesting people. Together, the videos had a total of 7,304 views. (You can see the full list of videos here.) This year, I'm going to be interviewing people at the Intelligent Content Conference in San Jose, California, February 26-28. The 2014 Intelligent Content Conference The Intelli... [Why I left the Mormon church](https://idratherbewriting.com/why-i-left-the-mormon-church/) Jan 16, 2014 • [family](https://idratherbewriting.com/category-family) 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... [Single-page docs versus "Click Insanity"](https://idratherbewriting.com/2014/01/12/single-page-docs-versus-click-insanity/) Jan 12, 2014 • [api-doc](https://idratherbewriting.com/category-api-doc), [findability](https://idratherbewriting.com/category-findability) 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... [Upcoming presentation to Sacramento STC Chapter on Jan 16](https://idratherbewriting.com/2014/01/12/upcoming-presentation-to-sacramento-stc-chapter-on-jan-16/) Jan 12, 2014 • [technical-writing](https://idratherbewriting.com/category-technical-writing) 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... [Tips for writing code comments in developer documentation](https://idratherbewriting.com/2014/01/11/tips-for-writing-code-comments-in-developer-documentation/) Jan 11, 2014 • [api-doc](https://idratherbewriting.com/category-api-doc) 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:

... [Recording of STC Berkeley presentation on why users can't find answers in help](https://idratherbewriting.com/2014/01/08/recording-of-stc-berkeley-presentation-on-why-users-cant-find-answers-in-help/) Jan 8, 2014 • [findability](https://idratherbewriting.com/category-findability), [podcasts](https://idratherbewriting.com/category-podcasts) Listen here: A few weeks ago I gave a presentation to the STC Berkeley chapter on findability of help content. The recording is available here: 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 presentation to the Berkeley chapter (this recording) differed quite a bit given... [DITA's output does not require separation of tasks from concepts](https://idratherbewriting.com/2014/01/05/ditas-output-does-not-require-separation-of-tasks-from-concepts/) Jan 5, 2014 • [dita](https://idratherbewriting.com/category-dita), [findability](https://idratherbewriting.com/category-findability) 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... [The appeal of DITA](https://idratherbewriting.com/2014/01/04/the-appeal-of-dita/) Jan 4, 2014 • [dita](https://idratherbewriting.com/category-dita) 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 ... [Upcoming API Workshop in San Jose on Feb 8, 2014](https://idratherbewriting.com/2014/01/01/upcoming-api-workshop-in-san-jose-on-feb-8-2014/) Jan 1, 2014 • [technical-writing](https://idratherbewriting.com/category-technical-writing) 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... [How to lose weight without starving yourself](https://idratherbewriting.com/2013/12/31/how-to-lose-weight-without-starving/) Dec 31, 2013 • [technical-writing](https://idratherbewriting.com/category-technical-writing) 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... [« Previous](https://idratherbewriting.com/page67/) Page: 68 of 174 [» Next](https://idratherbewriting.com/page69/)