Author Archive

June 18, 2010 Interesting Links

Jun 18th, 20100 Comments
, , news

Creating a Style Guide For Your Documentation: Part II

Jun 17th, 20100 Comments

CSS

Last week, I created a video about the importance of having a style guide for your technical documentation. It helps to save time and stress, so that you are able to focus on more important things, like the quality of your documents.  If technical writing isn’t your strong points, but you are pretty good with HTML and CSS, then using those skills will help you create an outstanding and effective style guide that will become the bible for the format, style, and presentation for all of your technical documentation.

Here is a sample of a CSS style sheet:

body{
margin:0px;
padding:0px;
font-family: Arial, Helvetica, sans-serif;
font-size:11px;
background:#000 url(images/bgr_main.png) repeat;
color:#3d3d3d;
}

#header_title h1{
color:#fff;
font-size:73px;
font-family:”Times New Roman”, Times, serif;
padding:10px 0 0 40px;
letter-spacing:-7px;
font-weight:normal;
font-style:italic;
}

.post-title h2{
font-size:27px;
color:#000;
font-weight:normal;
font-family:Tahoma, Geneva, sans-serif;
margin:0 0 10px 0;
}

.img.centered {
display: block;
margin-left: auto;
margin-right: auto;
}

As you see, you have to define every bit of your web site or blog, so that you can have uniformity.  It’s the same with your documentation’s style guide.

Cover Sheet

You will usually have a cover sheet on all of your documents. The information that should go on the cover sheet is:

  • Your Company’s Name
  • Your Company’s Address
  • Your Company’s Logo (Optional, but good.  It will give an appealing visual for the reader)
  • Your Company’s Point of Contact (This is if it’s going to be delivered to someone else)
  • Submittal Date (The date the document is supposed to be delivered)
  • Deliverable or Contract Number
  • Confidentiality Statement (Optional. I don’t really care for these, but some companies have them for legal purposes)

A page border will make it look really nice, but this is something that is up to your discretion. Also, there should not be a page number. Here is a sample of a cover sheet I did for a proposal.  I have removed my client’s information, but their logo, point of contact, company name, and address was on there as well.

cover sheet Creating a Style Guide For Your Documentation: Part II

Page Numbers

Page numbers are pretty easy.  The cover sheet (as stated above) should not have a page number.  All the pages before the Introduction of the document should be in roman numerals.  These pages usually include:

  • Table of Contents
  • Table of Figures
  • List of Tables
  • Control Sheet (Optional. This shows the change history of the document.  This is usually used for best practices, such as CMMI)
  • Document Review Sheet (Optional. This page is where the chain of command signs off on it)

The document’s body should be numbers (for instance, 1, 2, 3, 4, etc.). If you have appendices, use the appendix heading letter, a hyphen, and the number. For example, if it’s “Appendix A,” then you will number them as A-1, A-2, A-3, etc.

Tip: The best way to separate the page numbers is by using section breaks.

Headings

heading_style guide Like I said in the video, you should try to go down six levels.  Regardless of what word-processing software you use, they all basically behave the same way. You want to go to the Styles area.  There you will see Heading 1, Heading 2, Heading 3, and so forth. You can modify them. You want to have an outline by using font size, font style, and numbering. For instance:

Heading 1 is using Arial, Bold, and size 14.

1 Introduction

Heading 2 would then be Arial, Bold, and size 12.

1.1 Scope

Heading 3 would be Arial, Regular, and size 12.

1.1.1 Document Scope Info

If you do this correctly, then it will automatically do the dirty work for you.

Text

You also want to define the text in your documentation. Usually it will be Times New Roman, and either be size 10 or 12. However, there are times that you have tables that the background is dark, then you will have to define the color as well.

Paragraphs

paragraph_style guide

Paragraph spacing and indenting should be the next step in defining your documentation. You want to ensure that the spacing is not different from one document to another. It might seem like a small matter, but it really does a difference. You can decide that the spacing above a paragraph is 3.00″, and the spacing below is 6.00″. It shouldn’t be more than 9.00″ or it will make the document look weird. You could also indent the first sentence, so that the reader knows that a new paragraph is beginning as well.

Figures and Tables

table_style guide Figures and tables should be the same size, margin, and heading. You usually want to separate the two because they are not the same. The figures could have a border surrounding them, while the tables don’t. Also, the heading for the tables could be above the table, but the figures below.

Conclusion

I probably missed bits and pieces because every documentation is different. However, these are the basics that will get you started. You want to ensure that you define everything, so that if a new person joins your team, then he/she is able to pick right up without asking too many questions.


, , , , technical writing, tips

Digital Capital Week’s Media 2.0 Day Recap

Jun 16th, 20100 Comments

image

I got on the metro today and headed to Digital Capital Week’s Media 2.0 Day.  There were going to be discussions hosted by USA Today, Pew Internet Project, and National Geographic. I wanted to hear the talk by National Geographic, but I had to be back to the dark side by then. I was able to catch the end of the talk by Jeff Pulver.  Even just hearing the end of it, I knew that I had missed a great speech.  He was very direct and knowledgeable about social media and media today.

One of the best quotes from him was after someone asked what he thought about Facebook and its privacy issues.  Pulver answered,

“You’re a moron if you leave Facebook cause that is where the people are.”

It made made me chuckle because of how honest the answer was. He also announced his new project JustCoz.org.  It is a service that allows people to donate tweets to causes of their choice.  Pulver said that sometimes donating something as simple as a tweet is just as good as money.  Word-of-mouth is always the best marketing method, so having people tweet about your cause is a good way to increase awareness. I started a non-profit organization, Stop Alcohol Deaths, Inc. (S.A.D.), to bring awareness of dangers of drinking excessively.  JustCoz.org is a great platform to spread the word of our cause.  After hearing him talk for the last few minutes, I wished I would have caught his entire speech.

image

I was able to catch the entire speech of Lee Rainie from the Pew Internet Project. He discussed the then, now, and future of the Internet and how its affecting the world. If you weren’t able to catch his presentation, then he posted the slides online. Definitely check them out when you get a chance. Some interesting tidbits are:

In 2000, only 49% of adults used the Internet.  In 2010, it is now at 79%.  Also, only less than 10% use the “cloud.” Now? It’s up to 2/3.

He discussed anonymity on the Internet. There has always been the concern that the person you are talking to over the Net isn’t really who he/she says.  It is easy to create a pseudo name, picture, etc. It was kind of split as to whether anonymity would be monitored in the future, or it would still be easy to be whoever you wanted to be on the Internet. With virtual worlds becoming more popular, I wonder if we will be like the society of The Surrogates graphic novel in the future.  I also wonder if we will become like how it was in Ghost in the Shell. I guess all we can do is wait and find out.

He also discussed the Metaverse graph that I know all of us have seen.  It is discussing four technological areas, and what the future (or now) comes from each one.

Picture 1 300x218 Digital Capital Weeks Media 2.0 Day Recap

It’s funny, but that is definitely what is happening now.  Everything is Augmented Reality, Vlogging, 3-D technology, and visual worlds (think World of Warcroft).  Overall, I was very impressed with his talk.  He really showed how much we have advanced and how much more we will.  It made me think about the adults my children will become, and how they will use the Internet and technology in their lives.

I did learn an interesting and humorous term, “tweckle.” It is when you heckle someone on Twitter.  I realized that there is a lot of tweckling going on on social networking sites. However, I found more interesting how the Internet and technology has changed our terminology.  When you look at the dictionary, you see terms that wouldn’t have been there a decade ago. You wonder what others words will be added.  Maybe even emoticons?  That is stretching it, but it makes you go hmm…

Again, Rainie and Pulver are great speakers and bring up ideas that will make you ponder about them for hours to come.

Overall, I had a great time at my first Digital Capital Week ever, and I can’t wait to attend many more. The next one is Digital Garage on Friday.  If you are attending, come up and say hi. I’d love to talk to you.

Posted from WordPress for Android


, , , random words

Are You Attending Digital Capital Week?

Jun 11th, 20100 Comments

If you want to be an entrepreneur...

Starting today, Digital Capital Week (DCWEEK) commences with the opening party tonight at Longview Gallery where you can mingle with the technologists, entrepreneurs, creative types, etc.  Before we get to far, you might be wondering, so ummm…what is DCWEEK?

It is a week (actually ten days) filled with conferences and parties focused on technology and innovation in the Washington, DC area.  The great part about is that the majority of the events are free. Yes, you heard right, free.  Being that I just started freelancing, it is music to my ears. There are tons of events to attend.  On the site, you will find a schedule of events where you can go to the link to register.

The ones that I am really excited about are Media 2.0 Day and Government 2.0 Day.  Those are right up my alley.  I hope to hear some interesting discussion on the future of media and government.  It would also be great if I got to meet a few people who I can keep the conversation going even after the day is over.  I’m still sifting through the rest of the events to see which ones I can fit into my schedule.

All I know is that I definitely want to go to a few and meet some interesting people.  If you are in the DC area, and you have some time to spare, you should definitely check it out.  If you are going to Media 2.0 Day or Government 2.0 Day, come and say hi.

6.15.media20 Are You Attending Digital Capital Week?6.16.palantir.opening Are You Attending Digital Capital Week?

, , news
Page 5 of 62« First...«34567»102030...Last »