The Integration Engineer
When it just has to work.

One of the things that I advocate is keeping a copy of the documentation you produce, and the documentation that you encounter and use.  Over a short period of time, this can become a large amount of stuff.  If you are just throwing it all in your MyDocuments folder, it can quickly get out of hand.  To help out in this ongoing task and fight against the chaos, I am going to share some basic approaches that can help keep the sanity and utility in your documentation collection.

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?

Subscribe to "The Integration Engineer" by Email
Find out about the tools and services available at The Integration Engineer's Consulting site.

This entry was posted on Tuesday, October 13th, 2009 at 8:43 am and is filed under Documentation. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.