The Three Types of Project Documents

 

All project documentation can be given one of the following classifications:

1. Bridesmaid dress
2. Christmas tree
3. Monument

The first 2 were inspired by a line from Fight Club (about 1/4 of the way down).  Here’s how to tell which type you’re working on, with examples and how much time you should spend on each.

 

Bridesmaid Dress

A bridesmaid dress is important only to the bride, costs serious money and is thrown away after 1 wearing.  A bridesmaid dress document is a document that is just as expensive to create as any other document, whose sole purpose is to fulfill a process requirement, and read only once, if at all.

Like any other project document someone has to spend time filling in the control sections (e.g. version history, links to other docs, approver list, distribution list), in addition to crafting the real content.  The control sections take longer to fill out than the real content.  The content usually comes from a source to which project members already have access and could look up themselves if they really cared.  Project members must attend a meeting to review it.  Real time is spent, not just 1 person’s afternoon.

It is important only to the project manager because she is the one responsible for championing the process.  Mind you, it’s not her fault that it has to be completed, she’s just doing her job.  No one else really cares about it, though.

Only a few lines are relevant; many other pages won’t be read.  Even the relevant sections will be read only once, and only by the people for whom it really is relevant.  It might require 5 people to sign off, but only 1 will actually care about the contents.  Bridesmaid dress documents could easily be replaced with a maximum 10 line email, but no one creates template emails for projects.  Only a 10+ page Word template with a ton of control content will do.

An example is a test stage exit report.  Only the page with the defect status count summary is read by those interested.

As little time as possible should be spent crafting such a doc.  If you are starting from a template leave as many sections “N/A” as you can.  Only fill them out if someone asks, and even then with the bare minimum.

Christmas Tree

A Christmas tree costs time and money to assemble.  But the cost is borne because it is vital to those celebrating Christmas, and everyone benefits.  It’s enjoyed for weeks at a time, but after Christmas is thrown away or put back in the box for another year.

As with any project documentation, it costs real time and money to produce.  The template has all the same control sections as any other doc, like the bridesmaid dress doc, but the content takes much longer to produce than the control sections.  Team members review it, make changes that make it better and really read it before signing off.  People spend serious time on the doc but it is well justified.

A document of this type is a real necessity for the project.  Without it you couldn’t have the project.  People look at multiple sections multiple times throughout the duration of a project because it has useful, important information that project members must reference .  This doc is the first time in which this content appears – it’s not just a summary of other content.  The information feeds people’s efforts.  But it’s context is still limited to the project itself.

At the end of the project, though, the document itself is forgotten.  The content itself should be incorporated into a monument document.  Failure to do so will cause many future headaches because information is spread across multiple documents that no one can find.

An example is project business requirements for an application or system.  There’s nothing for a project to do without requirements.  They’re specific to the project, though, so they only express the changes, not the whole application or system.  By themselves they’re pretty useless to other projects, especially after the same requirement has been changed in a few projects.  They need to be added to a monument document to make sense across projects.

It’s totally appropriate to spend time on a Christmas tree document.  Everyone must remember, though, that it will be tossed aside or put away after the project and that the content must be put into a monument document to stay relevant.  Link to as many other project and monument documents as possible – don’t copy and paste content.  This is a waste of your readers’ time, and you’ll just have to spend time updating your copy when the source content changes.

Monument

A monument costs a lot of money, is relevant to many people and is used and lasts a long time.  Think war memorials, gravestones, the pyramids.

A monument document template has all the control sections of the other two, but are a tiny fraction of the total content.  The cost of producing the information may have been paid in previous projects.  Indeed, if you’re doing things right the content should already exist in Christmas tree documents, short of a complete rewrite of an existing monument document.  You’ll pay some time incorporating and reviewing new information, especially if the new info supersedes old info.  It’s well worth the cost, though, because people will be able to reference this one true source of information years later.

And people will reference it. This will be the authoritative source of knowledge about what a system should do, how it does it, how to test it or how to use it.  It will be your starting point for creating project Christmas trees and bridesmaid dresses.  Folks will actually enjoy reading it because it will be the one doc that others really care about and want to ensure its usefulness.  When you update it you’ll feel like you’re making a real contribution to something that will last longer than your employment at the company.

Which leads into the lifespan of a monument document.  It will be around as long as the thing it describes.  This could span a decade, even in technology.  I personally have worked on live code that is literally 10+ years old.  If a design doc had been written when the code was written people would still be updating it today.

Examples of monument documents are application or system design, or system/application requirements.  It doesn’t have to literally be a document, either.  A database of test cases or requirements would count too.  Really, anything that aggregates project-to-project changes and is kept up to date.

This is where anyone should spend serious time.  This is the most valuable type of document a company can own.  It will cut down on  new hires ramp up time.  It will be invaluable when you rewrite an application 5 years from now.  It will save you from mistakenly asking for a change that will affect changes made last year.  Such documents ARE your business.

This has been a summary of the three types of project document.  Hopefully it will help you spot the differences so that you spend the right amount of time on each one.

My Little Fermat

I didn’t have the heart to tell him that there is already a proof for when x>2.  He was just so happy with himself!

Everything That Glitters Isn’t Gold, But It May Be An Overpriced Used Car

Some signs a dealership paid too much for the used car you’re looking at, and won’t let it go for very much under asking:

1. It’s parked out in front of the dealership.  A dealership that also sells new cars of the same brand, that is.  As in, “look at this great car as you drive by and come in and ask about it!”
2. The engine is clean.  Very clean.  I mean like it just came from the factory.  Stickers are vibrant, metal gleams, even the black plastic is coated in something that makes it gleam.
3. The dealership is not serious about negotiating for your trade-in that is in above average shape.  They start waaaay below average wholesale, and won’t even consider offers near the average.

This was our experience recently when my wife and I tried to negotiate for a used Honda Element. 

When I saw the condition of the engine I thought all dealerships shined used cars inside and out.  Not so.  It was definitely an above average vehicle for it’s age (2008, ~55,000km), but it was dressed up and shown off out front. 

We may have been coming in a little low, but still above average.  We were sure the tires wouldn’t be replaced as part of Honda’s certification process.  They’ll replace tires under “40%”.  Considering the rest of the truck’s appearance I’m sure they would have already replaced the tires if they were below minimum.  They looked to be down to about 4mm, and would probably need replacing in about 6 months.  That was a $1000 cost we didn’t want to incur so soon after purchase. 

They sure didn’t seem to think too highly of our offer, and were obviously not interested in our trade-in.  For a car we could probably have gotten around $10,000 if sold privately they offered just $6000.  Basically, get your stinking car off my lot, you damn dirty apes.

So we walked.

They didn’t call us back.

We ended up finding a less “prestigious”  Element at another dealership that was willing to be reasonable.  It will come with new tires.

References

I would have thought the following was Visual Studio 101, but I’ve seen senior people confused by this, so I will elaborate.

If you’ve ever expanded the References section of a .NET Visual Studio project then you’ve seen the list of DLLs that your project can access.  Most of the items in a typical list are .NET Framework DLLs.  These are the Release build of DLLs, and they live in the GAC, or maybe somewhere in some Program Files directory if they are little extra packages, like the Silverlight Map Control.  Changing your project from Debug mode to Release mode doesn’t change the DLL link.  There’s only 1 available, the Release mode DLL from Microsoft or whoever.

Now, if you have a project in your solution that another project in your solution uses, (e.g. the business layer that your UI layer calls into) then there are at least 2 ways to add a reference.  One is a bad idea, and one is a good idea.  One way, the bad way, is the same as the references to framework DLLs – by referencing a particular DLL on disk.  The other way, the right way, is a project reference, which makes Visual Studio aware that project x depends on project y in the same solution.

If when adding a reference to another project in your solution you are using this tab then you’re doing it wrong:

See how you’re specifically selecting the debug version of a DLL in your project?  What will happen when you switch to Release mode and build your application?  It will include the debug version of this DLL, if it’s available on disk.  Not good.

The right way to set up a reference to another project in your solution is to use the next tab to the left, the Projects tab:

By using the Projects tab you get the following behaviour – when you switch your solution between Debug and Release build modes each project will use the corresponding build mode DLL from referenced projects.  That is, in Debug mode all Debug builds of referenced projects will be built and loaded.  In Release mode, all Release versions will be built and loaded.

There are a couple of ways of detecting references that were added using the Browse tab rather than the the Projects tab.  One way is to open .csproj files with a text editor and look for the following, which indicates a project reference:

<ProjectReference Include="..\DrinkLocatorMvvm.Data\DrinkLocatorMvvm.Data.csproj">

A non-project reference to a specific file will look like this:

<Reference Include="HtmlAgilityPack, Version=1.4.0.0, Culture=neutral, PublicKeyToken=bd319b19eaf3b43a, processorArchitecture=MSIL">

followed by a HintPath entry, which helps Visual Studio find the DLL on disk:

<HintPath>DLLs\HtmlAgilityPack.dll</HintPath>

If you don’t like looking at .csproj files then a dead give away is the behaviour of reference paths when you switch from Debug to Release.  Put your solution in a particular mode, say Debug.  Right click on the reference in one project to a DLL that you know is in another project in your solution, select Properties and make a note of the Path.  For example:

C:\Users\jmclachl\Documents\Visual Studio 2010\Projects\DrinkLocatorMvvm\Lcbo.Model\bin\Debug\Lcbo.Model.dll

Now switch your solution into the other mode, say Release, and check the Path property of the same reference.  If it has changed to the corresponding DLL version, then you’re looking at a properly set up project reference.  For example:

C:\Users\jmclachl\Documents\Visual Studio 2010\Projects\DrinkLocatorMvvm\Lcbo.Model\obj\Release\Lcbo.Model.dll

If it doesn’t change then the reference was added as a file reference with the Browse tab.  Remove the reference and re-add it with the Projects tab.

Using file references, added with the Browse tab, may build fine in one mode, e.g. Debug.  But if you, or someone else who has checked out the project from source control, perform a Clean before a Release build the compile will fail.  That’s because the debug version of some project doesn’t exist on disk.  One very bad solution for this is to perform a Debug build before a Release build, but that will still add a debug version of a project DLL to your release build.  How slow do you want your app to run in production with debug code?  And do you really want to suggest performing a Debug build before a Release build to the folks maintaining your build server?  They should laugh at you.  If they don’t then your company has at least 2 problems – you and the build server person to whom you’re talking.

Understand the difference between a project reference and a file reference and you won’t end up with broken builds or the wrong build version of DLLs in your bin directories.

Biggest Regret

I recently read an article about Donald Rumsfeld’s biggest regret (not pushing Jr. hard enough to accept his resignation after the Abu Ghraib abuses came to light), and it got me thinking about my biggest regret.

For many years my biggest and only regret was getting the arms on a leather jacket trimmed too short.  I liked to think that this was a nice only regret because it meant I didn’t regret any of my other life decisions, like the woman I married, the house and car we bought, having kids etc.

But I recently had to move a bunch of dishes and glasses given to us as  wedding presents.  It made me realize that my biggest regret was registering for wedding gifts. 

I appreciate the folks who came to the wedding and spent their money on us, but I regret not talking to more people about the whole idea of registering.  I’m sure I would have found out before it was too late that if you don’t register for gifts people will just give you money.  Register for a few gifts and they’ll give you a few gifts and a bunch of money.  Register for a lot of gifts and you’ll get a lot of gifts and a bit of money.   Get a lot of gifts and you’ll need to store a lot of gifts.  As a consequence I now just give money for weddings whether people have registered or not.

How this happened is, we went to the Bay and they handed us three things:

1. A cardboard wheel on which you rotate a circle to the number of guests you plan to have and it tells you the number of table place settings and total dollar amount for which to register.  I seem to remember it suggesting 16 place settings.  I don’t remember the total dollar amount.
2. A list of things that constitute a place setting.  From the gifts we received the list must have been:
1. A soup bowl
2. A salad plate
3. A dinner plate
4. A dessert plate
5. A white wine glass
6. A red wine glass (still can’t tell the difference)
7. A martini glass
8. A water tumbler
9. A champagne flute
10. A salad fork
11. A dinner fork
12. A knife
13. A dinner spoon
14. A tea spoon
3. A bar code reader with which you run around the store scanning the things you want to add to your registry.  If you want 16 of something you don’t even need to scan it 16 times, you just enter ‘16’ on the scanner and scan once.

These are your “good” dishes, not your everyday ones.  This means you have to store it all somewhere separate from your everyday dishes.  Which is the situation we’ve found ourselves in.  What do we do with a dozen wine glasses, a dozen martini glasses and a dozen champagne flutes?  Store them.  Move them around the house, carefully.  Use them once every 6 months.  In short, manage them in a high cost, low benefit manner.

So, for Jebus sake, don’t register for much, or anything, for your wedding.

I’m only in my 30’s so maybe I haven’t lived long enough, or had a high powered enough career to have a significant biggest regret.   I certainly  haven’t been the CEO of a multiple companies, or defense secretary of the U.S., so I probably won’t have regrets on the level of Donald Rumsfeld.  (Seriously, how does he sleep?  On a pile of money surrounded by many beautiful ladies.)  But I hope to hold on to this current regret as long as possible.

Better Bass On Your iPod

The iPod has an equalizer setting called Bass Boost.  However, for most modern songs this setting will cause a buzzy sound during bass-heavy sections.  As I understand it this is because most modern music is recorded very loud and the iPod doesn’t have the power to add the needed decibels.  One suggestion I read was to use iTunes to reduce the volume of all your modern music.  Rather time consuming.

The solution I’ve found is to go the other way – enable the Treble Reducer EQ setting and turn your music up.  This works best if you use headphones that produce really good bass.  I use and highly recommend the Klipsch Image S4 headphones.  With these headphones I’ve found the default sound setting has great bass but too much treble at higher volumes.  Reduce the treble and you’re golden.  The iPod doesn’t struggle to remove decibels.

(English is such a screwy language.  Every time I wrote the word bass I thought it was a type-o and that it looked like I was talking about fish.  We should standardize on “base” to mean low frequency sounds and the thing I’m in killin ur d00dz.  Leave the word that doesn’t end in e and has repeated consonants to be pronounced with a short and to refer to fish.)

What Would You Do if You Knew You Couldn’t Fail?

I recently watched a talk of Naomi Klein’s on ted.com, where she mentions that Tony Hayward, the CEO of BP at the time of the spill in the Gulf of Mexico, had a plaque on his wall with this phrase:

What would you do if you knew you couldn’t fail?

Klein’s implication is that when Hayward and other people ask themselves this question they get a deluded sense of the possible.  Unless a person is bipolar and has a psychotic view of his or her own abilities, I disagree.

The first thing that springs to most people’s mind is to do something illegal, like rob a bank, or kill someone.  In this case failure is interpreted as getting caught.  Ok, let’s say you actually did that illegal thing – could you live with yourself for the rest of your life?  If you robbed a bank while it was open, scaring tellers, customers and their kids could you live guilt free?  If you killed a person you definitely wouldn’t, unless you were a conscienceless sociopath.

Another thing that tends to come to mind is to do something that isn’t illegal, but is unethical, like cheat on your spouse.  Again, this is interpreting failure to mean getting caught.  And again, could you live with yourself?  I hope not.

So how should you interpret this question?  By thinking about the definition of failure in your imagined scenario.

As I stated above, failure doesn’t equal not getting caught, so this question isn’t about getting away with something.  Failure also doesn’t mean that succeeding would be a walk in the park.  “Having a 3rd/4th/nth kid” could be considered a good answer because even though you might have hard times, you can sort of define success (e.g. kid graduates high school/college/university without a criminal record and moves out).  Failure means not achieving a goal, and having not succeeded you don’t have any more chances.  If you have unlimited tries at a goal then you can’t really fail, you can only give up.  The goal also has to be in the realm of the possible.  Bringing someone back to life is not an acceptable answer.

So the question is about doing something where you only have one chance, or a very limited number of real chances.  By real chances I mean that even if you can theoretically try lots of times, people will remember you failing and not even consider you, like people who try out for American Idol again and again, or losing presidential candidates.

In Tony Hayward’s defense, I’m sure he didn’t think to himself, “I’d drill a hole deep into the ground that’s deep underwater with no testing and no safety measures in order to produce cheap oil.”  Like any sane person I’m sure he realized there is a follow up question:

Ok, cool.  Now, realizing that you could fail, how will you make sure that you don’t?

Oil companies have been drilling successfully in the Gulf of Mexico for a long time, and know the answer to this question.  Safety measures, testing, redundant systems, following documented and tested procedures.  Not doing these things led to the BP failure.  But I don’t think someone looked at his plaque and thought, “I’d bypass all known ways to succeed to save some money.”  If someone did think this, then he’s out of touch with reality i.e. a psychopath.  The mistake wasn’t in drilling for oil so far down, it was doing it in a really unsafe way.

The question is meant to inspire personal audacity, but with risk mitigation.  Was it a mistake to try to reach oil beneath 1.5Km of water and even more rock?  No, no more than it was a mistake to try sending men to the moon, or to leave Africa 70,000 years ago.  As Jim Kirk said, “Risk is our business.”  The Enterprise’s mission was to explore.  It didn’t go into space without defenses, weapons and the prime directive, though.  (Ok, Kirk was a little TS;DR with the prime directive, but I’m sure there were other captains at the time who followed it.)

By audacity, I mean reaching for a result for which the path is not clear.  Perhaps you think “remodel the kitchen” is an answer.  If you intend to hire a contractor, no, not a good answer.  You can throw money at this until it succeeds.  It has to be a personal challenge, too.  If your answer is “remodel the kitchen myself, even tough I don’t know what lefty loosey, righty tighty means”, then good answer.  This would prompt you to learn the needed skills to mitigate the risk.

Now for my own answers.  Audacious personal actions I would take if I knew I couldn’t fail:

• Get some of Milton Friedman’s ideas implemented in Canada, namely a flat tax, free immigration, negative income tax, voucher school system.
• Dismantle the CRTC
• Change the US Constitution to allow foreign-born citizens to become president
• Get Arnold Schwarzenegger on the presidential ballot (I think the rest would take care of itself)
• Strike out on my own as a free lance .NET C# developer
• Reunite Guns N Roses members at the time of Use Your Illusions and patch things up to the point that they could produce another album
• Convince MC Plus+ to create another album
• Prevent Jack Black from making any more movies
• Ensure Robert Rodriguez, the Cohen Brothers and Ridley Scott keep making movies until they fall over