How big should your documentation repo be?
How big should your documentation repo be, especially if you have multiple products in your documentation? Although you could put all content into the same repo, it might be easier to have lots of little repos. Jekyll accommodates this architecture quite nicely through gem-based themes.
Impressions from the Write the Docs Conference -- and thoughts on achieving sustainability without selling out to vendors
I recently returned from the 2017 Write the Docs conference in Portland, Oregon. The conference had two days of sessions (Monday and Tuesday), preceded by a day of doc writing sprints and workshops. I also participated in a 5-mile conference hike on Saturday. Although this was the fifth year of the WTD conference (it began in 2013), this was my first time attending. In this post, I'll share my impressions of the conference, contrasting it primarily with other tech comm conferences such as the STC.
Slides for Write the Docs Portland presentation on doc navigation best practices
Slides for my presentation on doc navigation are available below. I'm giving this presentation at Write the Docs Portland on May 15. The presentation is about 20 minutes long.
Testing your documentation -- updates in API doc course
Testing your documentation is such an important part of tech writing that I decided to expand the sections on testing docs in my API doc course. I actually grouped these pages into their own section, amplifying the content with more detail and better organization.
Write the Docs Podcast episode 5: Where do we belong?
In this episode of the Write the Docs podcast, we explore where technical writers belong in an organization. Is tech comm best placed within engineering, marketing, product management, or another group? We also talk about strategies for doc navigation, in particular, the merits of inline links and/or sidebar navigation, using a post from Every Page Is Page One as a starting point. Are hierarchical sidebar menus still useful, or are they a relic of the past? Finally, we provide details about the upcoming Write the Docs conference in Portland, and Chris mentions his new book on responsive design.
My Calm Meditation app -- another experiment to test my docs
I recently created an HTML5 web app called Calm Meditation. If you have a Fire TV, you can check out the app by searching for it in the Amazon Appstore. I'm not really into meditation, but I needed some sample video content to test out a web app framework I'm documenting. The idea I came up with for generic video content involved nature still scenes with some background music. I think it worked out okay, actually. There's a whole genre of these types of apps, apparently.
Tutorial on converting an HTML site into a Jekyll theme
I recently added a tutorial on converting an HTML site into a Jekyll theme. This tutorial shows how easy it is to make any HTML site Jekyll ready with just a few tags. Creating Jekyll themes is one of the aspects of Jekyll I enjoy the most.
Following instructions involves learning a new language -- adventures with Tinker Crate projects
In following instructions to assemble a Tinker Crate project over the weekend, I realized that a list of parts (essential for assembly kits) is similar to a glossary in that it teaches you a new vocabulary. Software projects also involve new vocabulary terms, but software instructions often omit the glossary (or list of parts). However, if you look at the glossary as a dictionary for new vocabulary, its inclusion in software instructions becomes just as essential as a list of parts in an assembly manual.
Write the Docs Podcast app now on Fire TV, and the importance of testing your docs with sample apps
The Write the Docs Podcast app is now on Fire TV. If you have a Fire TV, search for write the docs or even just technical writing in the Amazon Appstore and you'll find it. I created this app to better understand the Android app template I was documenting. This app template, called Fire App Builder, is designed for third-party Java Android developers creating streaming media apps.
Amazon begins pilot with voice-interactive user manuals
Amazon's technical writers are taking their manuals to the next level using voice-interactive features with Alexa. The guides are still delivered through traditional means (PDF and web), but these guides now include an additional interactive voice enhancement that users can optionally leverage when they get confused or frustrated.
Tutorials versus docs -- why you need both
There's a new tutorials section in the Jekyll docs. I actually added this new section and contributed a couple of tutorials there. I initially did this because I wanted to become more familiar with github workflows with open source projects, but I also just like playing around with Jekyll. In adding tutorials, we decided to distinguish tutorials from docs on the site. This division between tutorials and documentation is an interesting one. Most documentation could benefit from including more tutorials because tutorials help connect the dots in how you use the various doc topics together.
Moved my API doc site into separate repo
I recently moved my API doc course into a separate repo. Previously, I had the material inside my main site in its own collection. But I wanted to completely separate out the site into its own repo, with its own theme and configuration file and other settings. This will allow me to more easily output the content to other formats, such as MOBI and PDF. I'm happy that I did this, as I think it allows users to focus more fully on the content. It also makes it easier for me to generate the content into other outputs.
Simplifying my life and writing
For a while now I've wanted to simplify my life. When I tell this to people, almost everyone can relate. But the move toward simplicity isn't just about removing busy-ness. Simplicity lets you focus on the things you actually want to do, rather than those things you feel obligated to do but have no desire to do. I have a goal to simplify my writing style as well, using tools such as the Hemingway app and basic simplicity principles.
Guest post -- The effects of terminology consistency on the reader's comprehension and attitude
From a cognitive perspective, what do we know about the effects of terminology consistency on how our readers understand and 'like' our documentation? In this guest post, Yves Pierrot explores how the cognitive aspects of memory, reading, text comprehension, and search strategies potentially influence reader comprehension in tech docs. He admits that research in this area is lacking, so he pulls on his own experience and background in psychology as he reflects on principles such as priming, polysemy, and more.
Crowdsourcing docs with docs-as-code tools -- same result as with wikis?
Adding an Edit on GitHub button to my docs didn't have the immediate collaborative result I anticipated. In analyzing why crowdsourcing efforts succeed or fail, I decided to look back at my efforts with wikis some years ago. Docs as code provides new tools for simplifying authoring and publishing, as did wikis at the time. But crowdsourcing writing proves to be tricky no matter what tool you use. Writing doesn't break down into granular chunks that can easily be crowdsourced, so efforts to crowdsource writing will likely be the same. However, docs-as-code tools can empower people to author and publish their own content -- without expensive help authoring tools.