readme.txt vs. readme.html
I’m mulling over the idea of publishing some of the development tools I’ve created. For right now, I’m just looking for a simple way to allow “friends and family” to see my notes and source code for a few key projects. I don’t think many people on my list will have the time and energy to download and compile stuff (unless it’s something they happen to need right away). I personally like to kick the tires of interesting projects around a bit first by browsing the source code. So, what I have in mind is a web interface to a Subversion source code control repository. The idea of browsing my project folders via the web brings up the idea of using readme.html files. I’ve considered this idea more than once in the past.
Most of my projects have a readme.txt file. Typically, a readme file will include an overview of the project and, if it is a code library, a few key source code samples ready to copy and paste. In the past, I have considered using .html files or even .doc files instead of .txt files. I’ve stuck with readme.txt for two reasons: One, I’m mostly working in a programmer’s editor. True, many IDEs have built-in HTML editors, but they are usually slow to load. Two, all the worrying about fonts and styles can be distracting. Overall, both these problems introduce what I’m going to call friction for lack of a better term. When you’ve built up some coding momentum (and this is important to do for reasons I may one day get around to writing about), friction slows you down. Some types of friction are important to the overall goals of a project and just can’t be avoided, but if friction is avoidable, then I say avoid it and gain some coding efficiency. Over time, the overviews and code samples in a readme.txt file can be pretty important to a project. HTML (or Word) formatting is pretty, but it increases friction for no practical benefit that I can see. Thus, readme.txt instead of readme.html.
So, returning to the subject of browsing a source repository. I started thinking that maybe readme.html was not such a bad idea after all. All you really need, is <h1>, <h2>, <p> and <pre> tags. How much hassle could that be? Tables can be handy, right? So, first I started thinking about getting a global style sheet in place, next I started thinking about creating a template I could use to create a new readme.html. Then, I started to think about how much friction I was going to add to day-to-day development and what the benefits will be. It’s a tougher choice than it was in the past, but, for now, I’m sticking with readme.txt.