Have a plan of what you want the reader to understand.

When you start taking notes, you won’t have this plan, and that is okay.  Notes are mostly for yourself.  But by the time you start to create a document that you want someone else to read and understand, you will need to have a plan on what the reader will take away from the document.  Ask yourself, “Is this a ‘how to’, or a ‘how works’ document?”

There is some overlap and subcategories for these two general types, but in basic if you are documenting how to start the system, or documenting how the parts of the system work together, you will use a different approach.  There will be some examples in the ‘how works’ document that will be like the ‘how to’  and any good ‘how to’ explains some of ‘how works’ that is inherent in the doing.  But these two approaches produce documents that look very differently.

Where is this document going?

As a guide for the focus, (and if you are like me that you have to write documentation in several sittings), place a bold “How To” or “How Works” at the top of the document or where you will see it when you come back to continue with your documentation task.  This is just a direction guide.  So you will remove this before sharing this document.  And it is just a guide, you can still include how to and how works information when you need it to make your point and get the information across that you are trying to convey.

The purpose of your document is …

Another way to keep your focus and direction consistent is to write the summary first.  And I do mean first.  Lead the document with a paragraph that says, “This document will explain XXXX.  When you have read this document you should be able to X, Y and Z and understand Q.”  And this is a paragraph that you may want to keep when you are done.  It is nice to find a document that gives you exactly what you need.  It is even nicer when you don’t have to read multiple documents to find it but just the headings.

Break it down.

After deciding on the direction, and what your target take-away is, you will probably have more than one part.  Even if this is just a single page “How To.”  So you can now break this out by creating your topic headings.  Sections like, “Tools Needed”, “Access Needed” and “Knowledge Needed” are good starters.  Pick what applies to you.

If you don’t know what sections you should have, take a look at documentation that already exists and see how it is broken up.  This is not cheating.  Not only does this solve your problem of coming up with sections, but it can help make your documentation more consistent.  And documentation that is in a coherent format with other documentation in the same repository is easier to read and understand.

1. Having a personal copy means that if the systems that have the public copies become unavailable, you will still have access to them.
2. Some times projects that get shelved, lose their documentation.  If you have a personal copy, when the project comes back to life, you will not be starting over.
3. And you never know what future project you will be working on that will spark the memory, “Hey we solved a problem like this on this other project…”  And having the documentation for it will help you.

I have never regretted keeping a personal copy of documentation.  But I have always regretted knowing that I didn’t keep one when I could have used it.

Be sure to sign up to be notified when the video of the complete presentation becomes available.

So it goes like this:

850 is a Purchase order, and is sent to the Vendor

855 is an Order Response, and is sent from the Vendor.  It confirms, updates or rejects each line, or the PO as a whole.

856 is the Ship Notice. and is sent from the Vendor.  It may contain one or more lines from one or more orders and can indicate shipment of partial lines from a PO.

810 is the Invoice, and is sent from the Vendor.  It contains one or more lines from one or more POs, but generally people keep these to only one PO.

820 is Remittance, and is sent to the Vendor.  It contains information relating to payment.

If I had said this a decade ago, you would have thought that I was confessing to something akin to being a peeping tom or voyeur.  But today, everyone reading this knows that I am telling you that I look people up on google to see what the internet says about them.  If you have ever done or said anything on-line, (or if anyone has done or said anything that references you on-line) it can be found.  And it will be by someone at some time.  Don’t let this on-line first impression be random or worse, in someone else’s control.

Privacy verses Anonymity

I see some of you out their squirming to write something back in defence of privacy that you think you have a right to.  I am sorry to be the one to tell you, privacy and anonymity are not the same thing.  There are parts of your life and data that the law will protect.  Most of it is fair game.  (And game is the right word.)

Somewhere it got into our conciousness that if we use handles like “RubberDuck21″ or “CyberToad69″ that no one would know who we were, and we would be anonymous on the internet.  That sitting at home in your PJs, you can go on-line and create whole new, disposable, and  untraceable identities.  That what you do on-line is somehow protected and private and anonymous.  Well this has always been false.

Going on-line with an alias of “CyberToad69″ is just as anonymous as putting on a mask and going to a Halloween party.  It works until you start talking.  But as soon as you open your mouth, you start giving yourself away.  This means that if you go on-line, and shop, chat, blog, tweet, or search, there is data stored that makes a profile of you.  This profile was not created by the penetrating act of hacking and ID theft, it is just a gathering of information that you gave away, freely.

How to find People

Have you ever googled yourself?  If not you should.  You may have to use more than your name, especially if you are a John or Sarah.  There are some other Roy Hayward out there.  One is is a hairdresser in the UK.  He takes the number one spot on google for my name.  But he is not me, and no one is really confused.  When I google people, I generally have a few bits of information in addition to a name.

When you talk to someone on the bus or the plane, most people learn one or more places that you have lived.  We volunteer this information in casual conversation.  When we volunteer information we are surrendering some of our privacy.

So now we have at least the state, and most times the city.  Most meeting give away a few other things like gender and ethnicity.  Also if we have a family, etc.  If you are a professional, you may give out your industry and even your employer.  With these small and common pieces of information, it becomes obvious that I am not the Roy Hayward in the UK, but the Roy Hayward in Utah.  It works the same for you.

Armed with this information, people like myself go to google.com and search for people they wish to know more about.  People we have met, and want to do business with in some fashion.  I generally find out what I need and want to know; “Is this person real?” ” Are they who and what they said they were?”  Are the questions that I am answering.  When my daughters start dating I may go for the criminal background check, but that costs money.

Now I can see some of you starting to go through a bit of paranoia.  That is unnecessary.  There is nothing wrong with this, and withholding your name at dinner parties will make them less fun.  So relax.

Control your Message

The real question and purpose of this article is to let you ask yourself this question; “What do people find when they look for me?”  Yes we are back to googling ourselves.  If you are a member of an on-line community or social network like LinkedIN or Facebook, if you have a MySpace page or a blog, you should want people to be able to find those.  They tell who you are.  They tell your story.  You get to control the message.  There is going to be data out there that will include you, so be apart of it.

Now there are also some things that you should be cautious of.  Even if you purchase ID theft protection, posting you birthday, social security numbers and bank account information is probably bad.  Intimate details of medical conditions in the wrong forum might be bad.  You should used your judgement here.  There are lots of blogs out and about being safe on-line, so I won’t go into exhaustive detail here.  (but you should google them if you want to ready about online safety.)

What do you do?

Now here is the question.  What do you do? (or want to do but haven’t had the time yet.)  I have a LinkedIN profile, a Facebook and Blog.  I haven’t done MySpace yet.  I just haven’t gotten around too it.  If you look me up, I am not the hair dresser from the UK, he can have the top spot, but I am in the top 5.  There is also Twitter where you can follow me and other around.  What methods do you use to promote your information on the internet?  Remember, there will be information about you out there, so you might as well control some of it.

Originally published on BlogCritics.com, Jan 10th 2008, updated here Oct 20th, 2009.

Have a place to keep things:

This may seem really simple, but we are talking about more than the MyDocuments folder of your workstation.  First of all, as I stated in the introduction, putting all of your documents in this one folder will quickly reduce the usefulness to having the documentation to the point were you can’t really find anything.  So here is where you create a new place.  The easiest is to create sub-folders.  For me, I will start by creating a sub-folder for product user guides and similar documents that I collect while working on 3rd party applications.

I might start out with a folder for each product, but over time, will create a 3rd party application folder for all of these folders to be grouped in.

I will also need a place for EDI specs.  I like to keep mine active in the standards Editor, but need to collect the doc and pdf files that my trading partners send me.  I will create a folder for each trading partner to put their specs and sample files etc into and group these into an EDI trading partner folder.

Basically the idea is to group like things into logical folders.  Then group like folders functionally so that your MyDocuments directory does not become uselessly cluttered.  And it will help you retain and find the documents that you only need once a quarter.

Keeping Communications:

I save all my email.  If you email me right now at roy@theIntegrationEgnineer.com, you should know that I will keep that email for ever.  (unless you are advertising weight loss or have money in an account in Nigeria that you want my help with, those will be deleted.)  Your email asking a question, or making a comment will stay in my active email directory for about 4 months, and then be moved to my archive.  Where it will sit for several years before being moved to my longer term archive.  (I have email that goes back to college, when email was first introduced, and the internet was all text.)

You may think I am a nerd, (and you would be right), and wonder why I keep all of this.  It is simple, email makes a great database that can be searched to find out what happened, and when it happened.  Email often has documentation attached to it.  It contains contact information.  It has lists of names, events, and products.  Keeping my email has saved me several times as I am able to go back and find what I said, and what others have said in and integration process.   (It keeps people honest.)

I have seen some people go nuts with email folders and organize emails by sender and more.  I don’t do that.  But if that works for you, then do what works.  The worst policy I have seen is people who just delete email after they read it.  I can’t imagine this as they have just lost what I have said to them, and will be at the mercy of my archive of email if there is a dispute over that was said in the on-line email discussion.

Archiving the archive:

From time to time a project, product, or integration will become old.  Once you have stopped using a product, or application, the usefulness of maintaining a folder in your application documentation folder begins to decline.  When this happens, I archive the archive.  I do this by zipping up the directory using zip or tar or any handy standard compression tool.  I then delete the original directory.

I do this for two main reasons.  1st, the tar ball or zip file can be moved to my long term storage.  2nd, even if I keep in in the directory, its contents stop showing up in directory searches.  It also takes up less space, but this is much less of an issue with today’s monstrously large hard drives.

Using a Wiki:

Some data is not best kept in a personal directory, email history, or archive file.  Some data needs to be recorded and sometimes shared in a living repository of data.  Using a Wiki can be very useful for this type of data.

It doesn’t even have to really be a Wiki, you can employ using a shared document on a shared drive.  This allows more than one person to access the data, and make periodic updates.  However, Wiki technology is relatively cheap and easy to employ and can readily be used to not only track the changes, but also who made them.

Notes to company or project meetings, integration procedures, check-lists, and other documentation that helps members of a team to collectively access and update persistent data are stored in this central location that can be accessed securely, and backed up against data loss.  But it also means that you have to be able to connect to it to use it, so you may want to store some critical documentation outside of the on-line Wiki.

At this point I would like to plug Tiddly-Wiki.  It is a basic, free standing wiki that you can use and customize for your own purposes.  If you like, check it out and play with it.  Its free and easy to use.

Finding what you have kept:

It may not directly relate to how to keep you documentation organized, but becoming familiar with the search features of all of the places we have talked about is very important, and helpful.  Learn how to search your email archive.  Learn how to search your directory structures effectively.  The Wiki should be easy to search, but you should know that as well.

Keeping documentation, email, and other data is not very useful if you can’t find it when you need it.

What do you use?

And again, as I list the methods that I have used, I am sure that there are other ways to organized, keep and find data and documentation.  So what do you do?  And how well does it work?

In comes the Integration Engineer to make the system work.  Producing effective documentation at this point is important.  We want to make the system work, and then hand if off to the team that will support it.  If we don’t create effective documentation, this last step can never happen, and we will be unable to undertake new integration work because we are still supporting the first one.  And if we are a contractor, we need this even more.

1.  Have a plan of what you want the reader to understand.

When you start taking notes, you won’t have this plan, and that is okay.  Notes are mostly for yourself.  But by the time you start to create a document that you want someone else to read and understand, you will need to have a plan on what the reader will take away from the document.  Ask yourself, “Is this a ‘how to’, or a ‘how works’ document?”

There is some overlap and subcategories for these two general types, but in basic if you are documenting how to start the system, or documenting how the parts of the system work together, you will use a different approach.  There will be some examples in the ‘how works’ document that will be like the ‘how to’  and any good ‘how to’ explains some of ‘how works’ that is inherent in the doing.  But these two approaches produce documents that look very differently.

2.  Break the document into sections.

Unless your document is less than a paragraph, it should have sections.  If you don’t know what those sections could possibly be, keep reading.  If you followed tip #1, then you should include a section in your document relating what the reader will get.  The important thing is to logically organize your document into sections that allow the reader to get the most information from it, and to make it usable as a reference.

3.  Include the location/source of any tools that are used.

A good way to avoid the call at 2 AM is to ensure that your documentation includes any tools that are needed and how to get them.  Sometimes this won’t mater, the interface is the browser and the editor is VI.  But when that is not the case, you will want to reference any and all tools and how to get them.  You will probably want to include this near the top of the document so that the reader can know what they will need before spending hours only to find out they needed a proprietary widget that takes 2 hours to install.

4.  Include Levels of access needed to do tasks.

Just like tools, any specific access need should be documented.  If a a DBA is needed to complete a task, then say so up front.  This will not only prevent you from getting a call at 2 AM, will prevent frustration to the reader, and may prevent accounts from getting locked and other security measures from activating when people with less access than you try to follow you instructions.

5.  Include Screen shots.

A picture tells a thousand words as they say, and adding screen shots to your documentation helps your readers to not get lost and can show them something difficult to describe.  So take screen shots as you go through the process and then include the ones that help guide your readers.

The two places to include screen shots are; Where the description is insufficient to keep the reader from misunderstanding.  And when the interface the reader will see changes, each new page so to speak.

6.  Include code samples

Like a picture, sometimes a snippet of code is the best way to explain a process.  Especially if you are documenting a mapping or integration procedure that involves coding.  But even if you aren’t including code snippets can help explain to people familiar with reading code better than any explanation.

If your audience is not comprised of code readers, you might replace code with a flow chart or diagram to visually explain the process in place of code samples.

7.  Include real life examples.

If you have ever read a legal document, you know that excessive abstraction, (party of the first part), can be detrimental to comprehension.  Sometimes it is easier to say, “Fisher is a good example of an bidirectional EDI integration set-up.”  And then explain why.  Anyone familiar with Fisher will know immediately what you are talking about, and those not, now have a place to look and find one.  And you avoid multiple sentences starting with, “The Supplier.”

8.  Include check-lists.

I have found that many of my ‘how to’ documents can be reduced to a check-list for the experienced user.  After reading the steps for setting up a vendor 15 times, I just need to be reminded of the steps.  Now my explicit document with pages of screen shots and examples becomes a stumbling block.  I may miss a critical step because I am trying to page past the explanation that I no longer need.

So after all of the explanation is over, a check-list or overview can be an effective in making your documentation useful even after the user is familiar with the process.  This will keep the document in their hands for when something odd happens, or when someone new needs to follow the process.

9.  Follow your doc.

An important part of prof-ing your documentation is to follow it yourself.  Don’t just write down the steps from memory or notes.  Even if you are really really sure.  You still need to follow your own documentation, and do exactly what it says to do.  While you do this you need to pretend that you only know what the document says.

When you find places in the document where any knowledge is assumed, then you should at least reference that fact.  If My document says, “Now log-in to the database with system account.”  I need to mention that this step requires a system account on the database.  And I need to reference this at the beginning of the step.  You will probably not want to include the user name and password into the document for obvious reasons, but if someone following your document gets halfway through a step and then discovers that they need your level of access, expect a call.

After you have followed your documentation, you may want to get someone else to follow it and see where they stumble.  This is even better than following the document yourself, as the user will not know the things your learned on the way unless you have included that in the documentation.

10.  Save a copy

This may or may not be obvious.  Saving a copy does two things; First, it makes sure that no network or backup failure on the file server will lose your documentation.  You will never have to re-do all of the work.  Re-done documentation is rarely better if the first has been lost.  Second, you will be able to reference your documentation for future projects, use them as templates, examples of your work, and so forth.

Summary

This is not a ‘how to’ of writing documentation.  Each company will probably have an established way to document things, even if it isn’t followed.  While following that process will produce documentation, adding images, snips of code, requirements and so-forth will make your documentation stand out as authoritative, and excellent.  And it may also keep that phone from ringing with questions for clarification.