If you have a question, comment, project, need a favor, or all of the above, you can reach me here.

jeff [at] jeffrivers.com



Use this handy form.




Developing ideas. Making people who use technology happy.

Turning documentation over to users: Forums and Wikis

The idea of adding a wiki or a forum to your documentation set is a good one: “We’ll let users contribute their knowledge, experience, and questions to the documentation. Customers helping each other will make life easier for everyone.”

Unfortunately, like with many good ideas, the difficulty is in the execution. Let’s look at the big picture and some of the assumptions around using wikis and forums for documentation.


Five reasons why you should create outlines

Creating an outline is a valuable exercise when you’re starting a project. Here are five reasons why you should create outlines before you begin drafting content.


Everything’s a concept, reference, or task

That’s right – everything. Learn to think about technical information as a collection of concepts, reference material, and tasks is crucial to effective technical writing.

If you author your content in DITA, then you already know this. If you don’t use DITA, you eventually might, so why not start now? In the meantime, it’ll give you an important starting point for when you’re outlining your content.

Let’s look a little further at these topic types and why you want to use them to classify everything, starting right now.


Writing with the future in mind

Working hard is great, but working smart is better. Whether you’re just starting a new project or maintaining something ongoing, you should create your content with the future in mind. Here are a handful of questions worth asking to make sure your content will serve you well for a long time to come.



Shorter posts. Any topic. Because you can't always talk about work.



The wonders of the internet, from me to you.