How to write README file for the iOS project
Have you ever encountered a Github project where, despite spending several minutes on the page, you still struggle to understand the purpose and functionality of the application?
This is a common experience, often resulting from a lack of clarity and attention to detail in the project’s README. To address this issue, it is important to understand the key components of a well-crafted README.
In this article, we will delve into the essential chapters that every top-notch README should include. Please make yourself comfortable as we embark on this journey.
What is a README file?
A README is a file that provides important information about a project, including its purpose, usage and setup. It is usually placed in the root directory of the project and displayed when someone visits the project’s page on a version control hosting service like GitHub.
It helps new users to more easily onboard the project and can also serve as a reference for experienced members.
What is “.MD”?
The .md file extension stands for “Markdown”.
It is a lightweight markup language intended for one purpose, to be used to format text on the web with plain text formatting syntax.
With it, we can easily highlight titles, links, tables of contests, etc.
The following link contains formatting rules that are easy to follow and its application improves the quality of the document design:
https://www.markdownguide.org/basic-syntax/
What good “README” must have?
The purpose of a README is to provide information about a project functionality, required installations, usage instructions, and deployment process.
While there is no set standard for the contents of a README, as professionals, it is advisable to include several key chapters to ensure its effectiveness. These may include, but are not limited to the following:
- Project title
Something snappy and attention-grabbing, like “The Best Project Ever Created (Probably)”. One sentence about the project in this chapter is fine. You shouldn’t describe the project too much here, because that’s what the next chapter is for.
- Description
A brief description of the project, including its purpose and any key features. When someone who has never had contact with your project reads this part, they should have a broader picture of its purpose.
What was the motivation for the project and how does it help its users?
In this part our job is to “sell” the project and gain the attention of the readers. We simply want to raise their level of interest.
- Getting started
Instructions for how to get the project up and running, including any necessary dependencies and how to install them. If there are any known installation problems and tips on how to remove them, they should be added here. Why in the first place could these problems not be removed?
- Usage
Information about how to use the project, including any relevant documentation and examples. If projects require credentials, they should be included in this chapter.
Is there a constant period when the application cannot be used for maintenance? How do you get to the main features or what is needed to be able to use them?
- Architecture
Without a good understanding of the architecture, new developers may struggle to understand how different parts of the codebase work together.
Are you using MVVM, MVC, VIPER, Clean Architecture or Redux? Add a few sentences that will describe the motivation for that kind of architecture.
- Structure
In Xcode it is easy to understand folders structure, however, we can only benefit from writing it down. Future devs will have in their heads that every file has its place, and if they are not sure where they should put it, README is there to help them out.
- Running the tests
Uncle Bob wrote in Clean Code —
Tests are as important to the health of a project as the production code is.
That is why we all have them in our applications!
If your team had time, and wrote some tests, write the instructions on how to use them in this section.
- Deployment
If you deploy the application with some of the CI/CD platforms, describe how the deployment process is activated.
Are there any certificates that are required for deployment and where can they be created? Where are analytics and crashes tracked? In fact, I believe that your application does not have any crashes.
- Dependency
Weather it is Cocoapods, SPM or custom you should explain them in a details. Provide a list of libraries that are used and explain what they are used for. This is useful for two reasons:
- Freshly onboarded devs can just read this chapter and they will know why a certain library is inside.
- We will notice and remove any libraries that are no longer used and thus reduce the build time of the application.
If there are libraries that we take care of, they should be highlighted here so that future developers know how to maintain them.
- Workflow
A few words about how to create pull requests and report bugs. Write the form used for reporting bugs, if any.
- Design
What is your design tool, and are there any conventions which should be followed?
- Task board
Provide a link to the task tool and describe the way of communication and planning of tasks.
- API
If there is API doc you should link it. Also, briefly describe how you do networking.
Conclusion
Whether your plan is to reduce the onboarding time of future developers or to get the attention of potential clients for a project, a README is essential.
Since it is the first thing which people will read when they visit the project’s page on GitHub, it’s important that it is well-written and easy to understand.
If you’re not sure do you need it or lack the motivation to create it, I challenge you to list a serious project that doesn’t have it.
Here is the example of the README used in this blog.
Domagoj is a valuable member of our iOS team.
At Azikus, we design and develop top notch mobile and web apps.
We are a bunch of experienced developers and designers who like to share knowledge, always staying up to date with the latest and newest technologies.
To find out more about what we do, feel free to check out our website and Linkedin.
