The lowly README file is a powerful tool that’s hardly ever used by software development teams. Even when it is provided by a team, it’s almost never used effectively.
I basically already knew this thanks to my long experience with development teams. But the point was really driven home recently when I was tasked to transition software projects to a new contractor that had won the follow-on contract for the program I was on.
Note: (5/9/26) OK, this is ancient history now, so there’s no need to be coy. This was the transition from General Dynamics Advanced Information Systems to Raytheon, who’d won the follow-on contract. I was one of the people tasked to close down the contract on the GDAIS side. Six weeks after the shut-down, I joined Raytheon to work on the new contract.
Problem Illustration
In a software transition, the goal is to do a fair, honest and complete turnover of the software to the new vendor. This means that you want to give the new vendor a solid orientation in how projects are organized, including what each component is, as well as how the software is managed.
Unlike what many developers think, the code does not “speak for itself.”
Let’s talk about scope.
A typical project being transitioned included multiple git repositories (between five to seventeen separate repositories for the projects I was dealing with). Naturally, some documents were also transitioned, primarily document types like the System Design Document (SDD) and System Admin Guide (SAG).
What really happened was that the new developers were given access to all the repositories for a project. They quickly discovered that the SDD largely covered how the system was designed, not how the individual components were designed. And the SAG primarily covered how the system was operated; if the new developers were lucky, it might also include install introductions.
None of the documents covered how to do things like build the software, run unit tests or integration tests, package the software for delivery or deploy the software.
What was really lacking was information in how the software was managed.
A Model for Developer Orientation
One project, however, really stood out from the pack. Their team’s repositories each featured a README.md file with detailed information about the project. It was basically a text file, enhanced with Markdown for formatting. The program used GitLab (a web-based open source system with similar features to GitHub), which understood Markdown and displayed the enhanced content.
Their README.md file provided:
-
- Description of the Software
-
- Relationship to other Components
-
- How to Run Unit Tests
-
- How to Build the Software
-
- How Create a Deployable Package
Here’s an excerpt of the content from the README.md file:
XYZ Gem
FEATURES
The XYZ gem (a Ruby library, analogous to a Java jar file) provides the following
features:
• Generation: Once data is populated into the intermediate class representation
supported by the gem, then the data can be exported into XYZ XML.
• Parsing: Data can be parsed from XYZ XML documents and stored within the
intermediate class representation supported by the gem.
• XYZ Versions: Historically, new XYZ versions have contained various
incompatibilities with older versions. The gem's design allows for support
for multiple versions of the XYZ standard (beginning with XYZ 1.1).
INSTALLATION
If there is a local gem server running:
$ gem install xyz
Otherwise, install the gem directly:
$ gem install xyz-.gem
FOR DEVELOPERS -----------------------
BUNDLER
Bundler is the standard dependency management tool for Ruby/Rails
applications. For Bundler, dependencies are configured in the Gemfile
file. Note that the Gemfile contains the "gemspec" command, which
configures Bundler to reference the gem's GemSpec file, which is called
xyz.gemspec, to retrieve dependencies that have been documented for
the gem.
Dependencies that are installed and in use will be recorded in the
Gemfile.lock file, which is created by using Bundler's install and
update commands.
To install dependencies:
$ bundle install
To update dependencies:
$ bundle update
BUILDING
The xyz gem uses an adaptive gemspec file. What this means is that
the gemspec file actually contains Ruby code that actively pulls
together all the values for the gemspec settings that are needed in
order to build the gem. The only requirement on the developer when
building a new release of the gem is to update the ./lib/version.rb
file to include the desired version number string, e.g. - 1.7.
To package up the gem:
$ bundle exec gem build xyz.gemspec
This will create a gem file in the current directory. For example, if
the version was 1.7, the above command would produce a gemfile called
"xyz-17.gem".
RUNNING THE CODE MANUALLY
To run the code manually, perform the following steps:
1. cd to the lib directory.
2. Run the Ruby command-line interpreter.
$ irb -I .
3. At the irb prompt, type the following command to load all of the classes.
> require 'xyz'
4. You may now manipulate the gem's classes. For example, to create a
collection and dump what it contains, type the following commands:
> p = Xyz::Native::Collection.new
> p.title = 'Stuff Happens'
> p.description = 'This is a test.'
> p.dump
5. If you want to parse a file, create a new parser object, then call parse
file passing a file path as an argument:
> p = Xyz::XyzCore::Parser.new
> p.parse_file("file_path")
INSTALLING THE GEM
Once you've created a gem file, the following command can be used to install
the gem:
$ gem install
TESTING
Testing is required in order ensure that the gem works properly. The gem uses
RSpec as its test platform. Tests can be executed:
$ bundle exec rspec spec # From the top-level directory
Thus, this was excellent for orienting the new developers picking up the projects from us.
The Sad Norm
Sadly, that one project was the exception. The norm was generally no README file. If there was a README file, it had generally been automatically created by whatever tools were in use by the development team…and then never filled in with real content.
General Utility
I’ll grant you that not everybody is transferring projects to a new vendor. But it seems to me that while this particular initiative was relatively unusual, the general capability to quickly orient developers to the intricacies of a software component is of general utility.
Over time, every long-running project faces:
- Turnover
- Loss of Institutional Knowledge
- Ongoing Maintenance Pressures
More than once, I’ve seen developers assigned to fix a production problem with a software component that hasn’t been touched in a year or more. Wouldn’t it be easier if there were some way to make sure basic, vital information was available to developers?
Conclusion
The solution, of course, is the lowly README file.
It’s simple, really. Just document a few critical pieces of information.
Once you’ve done this, check the file into the top level of your git repository, where it will reside for the rest of the project’s lifetime. You’ve now created a bastion of knowledge communicating critical information across successive waves of developers.
About The Author
