Every developer must learn the art of creating a README file to explain critical information about their software projects to internal stakeholders and customers.
Within a software project, README files are extremely important because they serve as a point of entry into the project code.
A README file is a text or markdown file that introduces and explains a software project. It should contain information that is necessary for users and contributors to understand and work with the project.
The scope and contents of a README can vary based on the project, the user and the development team involved. Still, there are certain core components that all READMEs share. As a developer, it's important to learn how to create a README that includes these components in a way that best suits your project and organization.
How to create a README file
Plan to create a README file that's specific enough to serve as a comprehensive guide for new developers, administrators, or even users to understand and interact with the project. This can become overwhelming or unwieldy if you include too much information. It might take some iteration to find the appropriate level of specificity for your organization, so don't be afraid to experiment with your README, especially if your software project is complex.
Standard tools to author a README file include proprietary and open source markdown editors, such as Visual Studio Code (VS Code) and GitHub Markdown Editor.
For a cross-functional team of collaborators, it sometimes makes sense to draft the README using Google Docs or Microsoft Word and then publish the final version to markdown or plain text upon final approval.
Examples of markdown commands that could be used in software documentation.
Here's a high-level process for creating and publishing a README file:
Start with a standard README template that fits the project's information requirements. Your organization should include the template in your project artifacts library.
Name the file "README", one of the industry standards for such files. For example, README.md is a README file created in markdown and is readable in GitHub or GitLab.
Populate the README template with the applicable content. Make maximum use of bullet points, code blocks and tables to improve readability and organize information.
Place the README file in the root directory of the project in the case of a software project repository. Some SaaS and mobile app developers who publish their documentation online might include their README with online content and make it accessible from an application menu.
Save, review, and approve the README file for publication.
It might take some iteration to find the appropriate level of specificity for your organization, so don't be afraid to experiment with your README, especially if your software project is complex.
The process for creating and publishing a README file for a SaaS, cloud, or mobile application can vary, and that's okay. For example, suppose your organization is considering DocOps or agile documentation methodology. In that case, the README might reside on a separate docs site linked to the main application. A range of tools can come into play here to create README files, such as the following:
Static website generators, such as Hugo and Jekyll.
Online help authoring tools, such as Adobe RoboHelp or MadCap Flare.
Open source content management systems, such as Drupal or WordPress.
SaaS and cloud README files often target developer and admin audiences, guiding them through cloud deployment, service architecture, and interdependencies.
What should you include in a README?
When creating a README file for your applications, you must devise a standard format that the development team can use across applications and create a template from it. Take the time to capture README creation guidelines and a standard template so developers and product managers don't have to start from scratch. Having documented standards and a template in place also helps save reviewers from making formatting and content changes that might be out of scope and otherwise waste time.
Here are some critical components of a README file:
Component
Description
Project title
The README should have a project title, typically
or something similar.
Project description
Open source project README files might include a "How the project was made" section that might be part of the project description.
Table of contents
A table of contents should provide a list of all major README sections.
How to install the project
Provide clear, step-by-step instructions that allow someone with no prior knowledge of the project to get it up and running, including copying and pasting friendly command line snippets.
Usage
Include the basic commands with examples to demonstrate typical use cases for complex tools, such as a SaaS application. Link to more detailed documentation or tutorials on a support portal.
Configuration
If your software project requires configuration, provide copy-and-paste examples of configuration files or command line arguments detailing what each configuration option does.
Dependencies
List all required dependencies and provide instructions or a script to install them. State if specific versions are needed.
Troubleshooting
Provide a list of common issues and their solutions. For more extensive troubleshooting docs, direct users to your support portal.
Contributing
Open source software projects often include this section to explain how others can contribute to the project.
Lessons learned
Your organization can also use README files to share lessons learned during the project's development.
License
State the software license type and link to the full license text, which is essential for open source projects as more companies become more conscious of the software licensing of their enterprise software components.
Contact Information
Provide specific contact details for support or further inquiries, such as an email address or a link to your support portal.
Best practices for writing a README
Below are some best practices for writing a README file:
Like many technical docs, people don't read README files, so make it easy for readers to skim the files by using straightforward language, descriptive headings, a logical structure and avoiding jargon and complex technology.
Begin the README file with a "Getting started" section, including installation instructions -- if necessary -- that provide customers with a step-by-step process to get the software live securely and efficiently.
Outline any security measures, authentication mechanisms and environment configurations that the customer needs to understand or set up for a cloud or SaaS application. This documentation is crucial for maintaining security when the customer deploys the application.
Take a practical approach and be generous with examples such as code snippets, command line instructions, and walkthroughs enabling the customer to get live with your application.
List any dependency requirements of the software in an easy-to-find section of the README file.
Be generous with examples such as code snippets and screen captures that best demonstrate how to use the application.
Share links to your documentation, issues database, support and training content, especially if the application is complex.
Update the README as the project evolves by including the update as a task in the feature release lifecycle.
Creating a README file is as straightforward as your team makes it. Organizations that are reactive in creating README files produce inferior release notes as the technical writer or product manager charged with developing the README bumps up against the competing priorities that come with a product launch. README files should appear in the overall project plan -- not just the docs plan -- with a timeline that enables iteration to avoid a ninth-hour rush to write an entire README from scratch in the days and hours before product release.
Will Kelly is a freelance writer and content strategist who has written about cloud, DevOps, AI and enterprise mobility.
