Do you read ReadMe files?

  • Article

My intern this summer spent a couple of weeks writing a cool readme generator which takes bugs written using a specific template and generates the readme and known issues document we will ship with Visual Studio 2005. 

Last week, I spent a few hours with one of our Release Managers and our User Education author going through the readme, editing it for grammar and technical accuracy and fixing any formatting problems.  The final readme was checked in last Wednesday (a sign that we're really close to shipping).

After all that work and documenting the issues we know about, how important is the readme?

Do you read ReadMe files?  Do you read it before you install the product?  Do you read it after you run into an issue?

I've always wondered if people read the readme file.  To be honest, before I had to work on the readme, I never read any readmes before.  Now that I know what goes in a readme, it's the first document I read when I run into a problem.

Let me know if you do or don't read the readme file.  It'll help me figure out if we really need to spend all this time on future readme documentation.

Thanks!

Comments

  • Anonymous
    September 18, 2005
    For VS2005, I usually reference the uninstall information in the readme file. Beyond that, I would only look at the readme if I ran into a problem.

  • Anonymous
    September 18, 2005
    For release software, I generally skim the first few paragraphs and anything marked "WARNING! IF YOU DO NOT READ THIS SECTION NINJAS IN BLACK HELICOPTERS WILL DESCEND UPON YOU BOTH YOU AND ANY CUTE, FUZZY KITTENS IN THE VICINITY AND WREAK HAVOC ON YOUR IMMORTAL SOUL!" before installation. Otherwise, the readme is more or less ignored unless I run into a problem.

    Pre-release and 1.0 software, I generally read the entire file from end to end, just in case any unpleasant surprises aren’t yet considered serious enough for the ninjas-and-kittens warning described above.

  • Anonymous
    September 18, 2005
    I belive standardization of most software instalation processes makes me seldom read the readme file.
    Unless its something that's not a easy install - like VSTS .. made me read the installtion guide several times, one mis-step and you messed up!
    BizTalk 04 was the same (I hear they have simplifed it going ahead).

    I think if someone has to read the file then your installation processes are not good enough!

  • Anonymous
    September 18, 2005
    When I was in college and dabbled with drugs like linux, I did read README files because you had to. Install was usually a painful process, unless you had RPMs or deb packages. I personally don't read readme.* files on Windows because installation is much easier. If I run into issues I will read the readme.* files, though.

    For VS 2002 and 2003 I did have to read the readme.* since I can never remember the full msiexec command to install just the remote debugger on a machine. I do like that in Whidbey this is not a separate install as well (at least in the pre-releases).

  • Anonymous
    September 20, 2005
    Like the other commentors, I usualy only consult resources like readme files after I've run into an issue. Software isn't fully baked if large numbers of users have to keep the readme handy.

    It is nice to have those unresolved, last-minute, customer-affecting issues pulled together in one place and documented.

  • Anonymous
    May 26, 2009
    PingBack from http://castironbakeware.info/story.php?title=quan-to-s-visual-studio-extensibility-blog-do-you-read-readme-files

  • Anonymous
    June 08, 2009
    PingBack from http://quickdietsite.info/story.php?id=1652

  • Anonymous
    June 17, 2009
    PingBack from http://pooltoysite.info/story.php?id=9246