The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

Read me file


I would like to take a recommendation from a specialized people and I hope I find a good advice.

Regarding "Readme" file for small software, is better to write it as MS Word file or simply as a Notepad…?!!!
It contains the setup steps

Please I need a reply as soon as possible.

Thank you,
Hal M S Send private email
Saturday, February 18, 2006
Plain ASCII text.
argon Send private email
Saturday, February 18, 2006
If you really want my answer…it is that you should NOT need a readme file!! I think they are a throw back to the old days of computers.

Remember, users of computers have really changed in the last 6 years. Most people prior to 6 years ago were quite computer literate people..and things like a “readme” file were common.

Now, you need an installer…and a readme file should only be for technical advanced people, or known problems that occur during the install anyway.

And, if you REALLY must have a readme file..then plane text as other mentioned is the way to go.

I suppose part of the answer depends on the target type users also.  There is no use filling up a readme file with technical install jargon if the end user can’t make heads or tails of the readme anyway. Users today are NOT technically advanced, and those readme files have a history of being targeted to people that will actually read the thing...and if they do read it..then they are likely to be able to understand it. (today...people don't read the file..and they are even less likey to understand it if they do!!)

Albert D. Kallal
Edmonton, Alberta Canada
Albert D. Kallal Send private email
Saturday, February 18, 2006
I think it's a circular argument - most casual users are not aware of the existance of README.TXT and wouldn't understand the significance.  :)

But Albert does raise a good point - a good installer should be able to do everything for the user; I've seen packages that use Perl shell scripting to ask basic questions and configure the application as needed.

So, if you're planning to sell the software, I would take the extra step as opposed to depending on a README.
Saturday, February 18, 2006
Use plain text, HTML, or RTF format. That's RTF as saved by Wordpad, not Word. People may not have Word installed (amazing, I know!) and Word puts tons of crud in its files.
Chris Nahr Send private email
Sunday, February 19, 2006
Thank you every one...indeed
I appreciate your advices

Best Regards;
Hal M S Send private email
Sunday, February 19, 2006
I agree with the previous post. We've made the decision not to include a README file. Instead, we distributed our programs with an FAQ.txt file, in a FAQ format identical to the one on the web site, and pointed out that the FAQ on the website is the most up-to-date version if they need it.

FAQ's are easier to skim and to read, and we've received good feedback for this 'feature'.

The FAQ, BTW is also placed in the application entry into the windows "START" menu for easier access.
Andrey Butov Send private email
Sunday, February 19, 2006
Once software is installed, it may be quite helpful to the user that Readme/FAQ file could be watched/launched using the program (example: help menu). Even when it's just a txt file, don't force user to get it only by hand (Explorer).
Ross Sampere Send private email
Sunday, February 19, 2006
Plain text, notepad readable.

And though a 'readme.txt' file shouldn't be necessary, it's an awfully nice place to put "late breaking" information, and perhaps even a revision history for the user.
Monday, February 20, 2006
Instead of TXT or RTF, why not HTML (which supports hyperlinks)?
Christopher Wells Send private email
Wednesday, February 22, 2006

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
Powered by FogBugz