Lesson 6: Modifying Styles

In this lesson, I want to take some time to focus on the "prettiness" of our output. Perhaps I'm a little type A about this, but I absolutely like things to look nice, even during the development process. I hate for things to look ugly. When I first became a technical communicator, I started (as most of us do) in the desktop publishing area. Essentially, I took someone else's writing and made it look pretty!

One of the strengths inherent in many of today's documentation tools (including MS Word) is the ability to separate the content from how it will appear to the end user. This separation is possible because of styles.

Styles are typically defined in a separate file from where you are creating your documentation. In the example you will see momentarily, I am using MadCap Flare, which utilizes a separate style sheet with a file extension .css. Every new topic is automatically associated with this file. The definition for each element in my document is stored in the file and then accessible from the topics I create. For example, if I want the title element to be 15pt bold Times New Roman font, I define it in the style sheet file and then apply the Title style to the text I want to change. Here's a demo of this very idea:

The style sheet can be modified for both online and print mediums in Flare. Watch how I modify the paragraph style (p) for print with a serif font here.

Your homework is to modify the default style sheet to your heart's content!

Lesson 5: Creating and Managing Topics

Now that we have our initial project configured and our renaming done, it's time to start creating! This is arguably my favorite part of the process. I love documentation (obviously) and as soon as we get through with this series about multi-purposing and reusing, I'm going to do a series of lessons on the writing process.

Today, let's look at how to create a topic with reuse and multi-purposing in mind. First, creating a topic. The following screencast describes how I take one of the sample html files we created in Lesson 4 and make it my own.

As a side note: I'm going to be using Screenr for my videos from now on. I recommend picking a product and staying with it. Having your resources in too many places is a bad habit and will not make your documentation any easier.



Next, let's look at how to consistently apply styles to our text. This is CRITICAL to preventing gray hairs when the committee decides the font is too large or needs to be a different color. Instead of having to modify each file one-by-one, we can simply modify the stylesheet and all topics/documents that are part of the project will be updated immediately! By the way, this is a huge time saver when using Microsoft Word/Excel too! Try to apply styles consistently.



Finally, let's look at how to create a new topic. This will be handy when we run out of Flare's sample project topics!

Lesson 4: Getting Started

Voice back: check; work conference over: check; child's school activities finished: check... And that's what tends to happen in the life of a writer - life gets in the way of what we like to do best!

Today, we're going to focus on getting our project started. I'm going to record a couple of videos using two of my favorite free screen casting tools: Jing and Screenr. Both are robust programs that let you record what you are doing on the screen in 5-minute bursts.

Neither product allows you to edit your recording - for Jing, you can upgrade to big brother Camtasia Studio to get full video editing capability. The major difference, and it's kind of a big deal IMHO, is that Screenr only requires that you have Java installed. If you do, you're ready to go - navigate to the website and start recording immediately! Jing requires you to download and install a client onto your computer. Jing has the added benefit of allowing you to capture screen images in the standard graphic formats.

Before going much further, it's a good idea to point out that I'm using a Logitech headset here at home. It's a mid-range edition around $45.00 and works fairly well. At my day job, we invested a little bit and bought a great little Samson GoMic. This thing is awesome! Crystal clear audio in multiple directions - and it fits in your pocket! Check out my Amazon widget to the right to get links to both of these tools.

Alrighty then! Let's get our project going. Video 1 demonstrates how to start a project using MadCap Flare. This video was completed using Screenr. Note that you can see it full screen by clicking the funny little square icon at the bottom of the screen.

Now, let's look at how to get cleaned up a little so we are ready to go for tomorrow's lesson - creating a recipe! Video 2 (completed using Jing) demonstrates how to take the sample template project and clean it up a bit to make it relevant to the project we are creating. Make this recording full screen by clicking the funny little TV icon in the bottom right corner of the screen.

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.

Wired and Weird...beat that

Right this minute, I'm blogging on my Samsung Galaxy Tab, answering email on my Motorola Android and playing the "with friends" games on my iPhone. Oh, let's not forget watching a recorded show on my PVR. Even for a gadget lover like me, that's a little too wired... Okay, and weird.

Hmm...could this be one extra-large Blue's clue to why I am struggling to stay on top of things and why I am not actually enjoying life at the moment? 

Since I don't feel equipped to address my wired habit, let's address a new weird one. In retrospect, I shouldn't be surprised. I come from a long line of vain (and rightly so) women. But I did surprise myself...I had Botox...and I love it! Does it make me vain? Probably. Does my new love of botulism make me weird? Undoubtedly!

She's baack...

I took a hiatus from blogging mainly because I didn't feel like I had much going on that was interesting enough to document. Interestingly, I suddenly don't care whether my posts are interesting or not. I feel like I'm growing so quickly lately, I have to document it or I'll miss all the lessons!

Latest lesson - my family is flippin' precious to me. Warts, quirks, and puppy dog tails, I'll take it all. We never have a dull moment and thank God for that. You see, I nearly killed us all the other day. I had a brief moment of domesticity and actually cooked a dinner... and then didn't completely turn off the gas range

Believe me when I tell you that 24 hours of gas running (even at a slow trickle) will fill your house up and it's not good for you to breathe (duh). We are all OK but I'm still feeling incredibly guilty. I think mainly because I'm so busy I'm never really there. You may see me but I can promise you my brain is already 4 hours ahead worrying and wondering about how I'll handle the next fire, the next big project, the next whatever.

Blessed!

So here is the take away...be present. You only have today and this minute one time, be present in it. My daughter will only be 5 for 365 short days, my husband is quite interesting and always fun to be with, my grandmothers, mother, aunt and father are still living and have great experiences to gladly share with me. What am I so busy doing that I can't look at these gifts and just be without any agenda?

So here goes...presence is the new thing. Let's see what happens now baby!