Lesson 3: The Setup

Ok, if you're following along, we looked at the tools we will be working with and the project we have been asked to complete. Even though we established that I would like to jump in feet first and start creating this project, I asked you to plan with me. Specifically, I wanted you to think about your project from a high-level perspective.

The answers to the questions from the first two lessons will set you up for success. So here are yesterday's questions and my choices:

• Should all recipes include the same types of general information? (e.g., Prep Time, Cooking Time, Number of Services, etc.)
  
  Yes, of course! This means that we should probably create a topic template, which will help us reduce time to create a recipe and also ensure we remember all of the essentials.
  
• How should we organize this project?
  
  This is a matter of personal preference. We have to think of this in a couple of different ways: 1) File Storage—easy enough - we can just create a directory structure to help us organize our recipes by type. 2)Table of Contents—we will need at least 5 of these - 1 each for: the complete cookbook (print edition), the complete cookbook (online edition), appetizers, main courses, and desserts.
  
• What conventions will we use?
• What styles are appropriate?
  
  Even though it takes time and is one of the more boring parts of the project, consider taking the time to create a style guide. In my case, I want to define how I am going to abbreviate measurements, whether or not I want to use passive voice, etc. Here is a sample style guide to get you started.
  
• How will you receive an approved recipe and in what format? (this is huge! If you take time to create a simple Word template everyone can use to submit a recipe, it will save you tons of time later)
  
  Take it from someone who has had to contend with content created in a variety of sources from plain old Notepad txt files to InDesign files to Excel files, save yourself some time and headache by creating a simple Word template for content contributors who will not have access to your Flare project. In the software world we call these Subject Matter Experts (SMEs) and (as much as I love my SMEs) I never want them within 50 feet of my Flare project as I'm sure they don't want me anywhere near their code. :)
  
  Here's my recipe sample template to get you started.

Check your work and see how your solutions lined up with mine. Remember that there is no right or wrong, there are going to be different solutions for each project. 

I promise that very soon we will start working on our project! However, I can't stress how important this prep work is. If nothing else, it will save you time in the long run! Happy planning!

Lesson 2: The Project

In Lesson 1, we looked at all the tools we will be working with for this project. Now it's time to find out about our project. As I mentioned before, my proven ability is in software documentation. While there is certainly a need for good software help, that's not the only kind of information we can create.

Project: Cookbook

You volunteer for a charity group that is raising money to build some houses in your city for people who have recently become disabled and require the use of a wheelchair. The houses must be fully wheelchair accessible, which will require special skilled labor to create.

To raise money quickly, the charity group has decided to compile a cookbook of recipes gathered from local celebrities and home cooks from your city. As each recipe is received, tested and approved, it will need to be added to the cookbook.

The cookbook committee has appointed you to compile the approved recipes and place them, along with appropriate pictures/videos depending upon the output. Committee members have voted to produce the following:

• A complete cookbook with sections for appetizers, main courses and desserts
• Smaller cookbooks for each of the sections mentioned above
• An online, subscription-based recipe site

Planning vs. Jumping

I'm totally a jumper at heart! I want to open up Flare right now and go to town creating everything. If you're a jumper, you're in luck. Flare is totally forgiving - it will allow you to move, rename, and retag to your heart's content.

HOWEVER, I have been doing this for 15 years. The value of planning has become increasingly apparent over the years. My recommendation, as much as I hate to admit it, is to do a little homework. Sit down and plan a bit. Decide some things up front like:

• Should all recipes include the same types of general information? (e.g., Prep Time, Cooking Time, Number of Services, etc.)
• How should we organize this project?
• What conventions will we use? 
• What styles are appropriate?
• How will you receive an approved recipe and in what format? (this is huge! If you take time to create a simple Word template everyone can use to submit a recipe, it will save you tons of time later)

If you are writing by yourself (without a team) you may be able to jump right in and handle each situation as it arises. Again, the tools are pretty forgiving. If you are working with a team, it really makes sense to have some planning meetings to discuss the bullets above. Additionally, you may want to look into source control. A Flare (or RoboHelp) project can only be opened by one author at a time. You must have a source control  system to allow multiple authors to work on the project at one time. We'll discuss more about this later, but it's worth thinking about before you start.

Homework

Pretend that you're a planner and want to have all your ducks in a row before starting this project. Answer the questions above and then watch for the next blog for the decisions I chose.

Lesson 1: Toolbox

My mission is to help you create awesome, helpful end user documentation that will make it easy for you to share your knowledge, repurpose it over and over, and produce many different outputs. I'll admit my forte is software documentation; that's what I have done for the past 15 years and it's what I am best at. However, I am choosing a project that will illustrate how anyone can use tools I will discuss indepth to make any other kind of knowledge sharing just as easy.

So, here we go—let's kick this thing off by listing out the tools we will be looking at over the next few weeks:

• MadCap Flare
• Microsoft Word and PowerPoint 
• Adobe Reader
• Screenr.com
• Camtasia Studio
• Articulate
• Snap!

Your assignment is to have a look around at these products. See what looks helpful. I have included expensive and free products and everything inbetween in the list. Have fun researching and then move on to Lesson 2.

P.S. Content Management System vs. Help System

Before we get much further into this thing, I want to address Content Management Systems (CMSs). This blog is not about CMSs. I think a CMS is definitely a great tool for knowledge sharing. Whether you choose to use one or not depends entirely upon your audience and whether or not you want to multi-purpose your documentation.