Imagine joining a project with a pretty large code/design base. There are two ways this story could go: You could pick up the material quickly and get on to doing your work effectively, or your could get bogged down in trying to understand code/designs that no one bothered to explain. Generally what makes the difference between these two senarios is documentation. Well written READMEs and associated documents are a godsend to new members of a project. Because of this, documentation is one of the most important pieces of a project or any work of development. As the makers and maintainers of such projects it is our duty to make such seamless transitions possible with good documentation.
This is not just commenting code, although that is important too. Proper documentation means actual documents, detailing systems, protocols, and example usages. This can be an arduous task, but do not fear: documentation is here! Fortunately for you developers and project managers out there such writing is made easy by things like this very article. Here are just some of the common practices, important features, and useful approaches that we have found useful in DALI Lab projects.
README
Where to start? The root file, the document that all but screams for attention, is the README.md. The README is what people of all backgrounds examine first. This could be new developers, designers, management, or interested third parties, so it should describe the project, detail install/setup instructions, and so on. A good README is like a well timed quip: it’s all about the delivery. README’s should be something people want to read, so keep it concise and abstract.
Pro tip: write a README.md file using the handy text rendering language called Markdown. Take a look at the markdown cheatsheet so your readme can look nice.
Basic format
The following is a quick README.md description and order of the sections.
Intro paragraph
- Description: what the project is, who the partners are, what the product does.
- (Optional) Add screenshots, icons, or designs of the product at the moment
(Optional) Associated documents
Include what you want, but be brief. Don’t go listing everything you ever made for this project. Keep it down to the essentials. If you need more room make another markdown file for links to resources and the just link to that one.
This might include
- Links to other pieces of documentation in your project (testing, coding, etc)
- References to other related repos (like a server, bot, etc.)
- Links to design folders
- Style guides
- User Personas
Tech Stack/Architecture
This should be a list of the technologies included in this project. It should be concise; maybe a bulleted list with one sentence for each technology on how you used it. You should include:
- Links to websites or documentation
- Descriptions of hardware dependencies, required operating systems, and so on (eg. If you are creating an iOS app mention which iOS is the development target and what was the highest version the app has been tested on)
Setup/Installation/On-boarding
It is crucial that you describe the intricacies of setting up a development environment. If you are using an Atom package that you suggest, add it to this step as a suggestion. Some notes:
- Don’t overlook global command line tools just because you use them every day. Explain how to install brew, cocoapods, gem, or npm if you need them.
- Keep your instructions consecutive, clean, clear, and concise
Deployment/Running
Describe how to run the application. If your program has multiple build configurations, flags, or whatnot, describe what you can in a couple sentences or bullet points. If it requires more explanation consider creating another file for deployment details and keeping the basics here.
Troubleshooting
Consider situations where the installation or running may fail or it wont compile after install. Try to give a couple of suggestions to people who may have those problems.
(Optional) TODOs
It can be good to have a checklist of things you haven’t finished yet, partially for organization and partially so people can quickly know if the feature they are looking for hasn’t yet been implemented but is coming.
For some projects you will have a “partner” (a client for whom the project is being developed). If there is someone who you will be handing off the work to it is a good idea to create a checklist for them so they know what steps they need to take to complete the handoff when it happens. This could include:
- Creating iTunes Connect accounts, Heroku accounts, web hosting systems
- Transitions of GitHub repo, the Drive assets folder, the team Trello Board, etc.
Authors/Contributors
List the people who have been involved in the work on this project an their roles in that work
Acknowledgments
Being respectful to those who have helped you along the way is not only courteous, it will make the people who helped more interested in working with you again. Reference people, websites, images, or anything else that has helped or inspired you.
Examples:
Pros:
- This README is well organized. Starts with documentation and architecture so people just getting started can explore the information given about the project and the hardware/software platforms they will need to be familiar with first. It then goes on to setup and more
- Detailed on-boarding instructions, tech stack, team members, and even Acknowledgments.
- The setup section contains a handy set of things that could go wrong and how someone might fix them. This is very important, as new members will not always have the ability to ask many questions of the past team.
Cons:
- The setup instructions should include Xcode setup
- Generally pretty short, which can work in it’s favor, although it misses the opportunity to delve deeper into on-boarding
This was a framework constructed to allow DALI members to make their own internal tools in iOS, tvOS, and macOS.
One notable feature of this README is a small set of images detailing things like CI build status, the current released version number, license type, and available platforms. This is really useful in the case of a framework, as someone just looking up your repository will find a version number or other pertinent information useful.
Pros:
- The README is well written, even showing build status, license, and platform icons.
- Since this is a framework there are some adjustments to the README, like showing a version number so the user can compare it to the version she/he is using.
- It is very thorough in the description of setup and simple usage, which is great for someone just starting to use the framework.
- It describes its super simple usage and defines a glance at what is possible with this framework
Cons:
- It brings the reader immediately into usage. This is risky, but if the setup is simple it could work. In this case it does not, so it could improve by cleaning up it’s setup documentation and describing Tech Stack/Architecture first.
- The order is somewhat mixed up. It starts with how to get started once installed, then mentions how to use it, and then mentions how to install.
- Could use more description of the framework and a better indication of why to use it
Mappy is an internal DALI project that shows on a map where members are from.
Pros:
- It has a good paragraph describing what the enclosed code is for, and it includes a walkthrough of how the user is expected to edit it, including step by step suggested actions.
- It has clear expectations on requirements.
- There are links to useful documents that people reading the page might need.
- Nice visuals to indicate how the product works.
- It may seem like it is missing setup but the Dev and Des links are documents on each role’s instructions. Both are lengthy, not something we want in the READefME, so it is good that they are in separate documents.
Cons:
- No mention of the collaborators on the creation of this project.
- No troubleshooting section.
- Missing acknowledgments.
Pros:
- This one has a great short description of the project and what the code is for.
- The device screenshots give us a look at the current product (it is nice to understand what features are going where in the product and how the user is expected to interface with the product).
- Well defined architecture section, with a bonus of explaining the organization of such architecture, like React-Native for front-end and Firebase for backend…
- Includes Tech Stack to describe hardware and software dependencies.
- Lists a project structure which is important for them as their organizational system depended on many root directory folders (the bullet points are great here, as each item has a short description that informs but does not clutter).
- The all-important Setup section is even more important for React-Native apps as clear install instructions are imperative when using the NPM package manager.
Cons:
- Almost too many screenshots. This is meant to be a quick overview, but too many screenshots can be overwhelming.
- It doesn’t mention what operating system they are developing for (iOS 9? 10? 11?).
- They could use a small troubleshooting section to describe some problems that could come up in setup and how to fix them (like Grafficity).
Code Docs
Commenting all your code can be a pain 😓… So when you are done you can take a nice break and write documentation instead 😉.
Some best practices:
Modularize
For each set of files that construct a functionality or feature, create a Markdown file to accompany it. The future developers on the team will consult these files to get a sense of project structure and how to edit this part of the project. Describe what it does, including how it fits into the rest of the code base, details on some of the more complicated functions and protocols, and approaches to modifying the involved code.
Ignore simple or non-central files. These are peripherals which are less likely to concern future programmers, so its not worth the documentation as long as the file is well commented.
Have an index/link page
Create a top level Markdown file that has links to all the other documentation with a short description for each (so someone can find what they are looking for quickly). This is a sign of exceptional documentation, as it can easily be searched and gives an overview of reading material.
For those files that you don’t document, mention them and describe briefly their function/meaning.
Top level protocols
In your index/link page describe how files fit together by organizing them into a hierarchy. A programmer who knows that the file they are modifying is used by 3 other files will be more careful to either not bother the “inter-file protocol” or take care to change it in all the connected files.
If there are any ways you store data (NSUserDefaults, document file structures, etc.) describe how they are named, where they are saved, what the format is, and the meaning of that format. This way developers don’t have to search through your code or documentation to figure out how you are using a file.
Leave the some of the work for the 3rd party
Don’t bother documenting how to use the frameworks you use. They should be documented well enough by the people who made them (and if not your documentation is not the place to describe their work).
Network Communicaton
Create a file that describes how your application as a whole uses network communication. Briefly list the sorts of network communications you are doing and what format the data should be in. If you are connecting to a documented server, link to the documentation for the functions you are using. If not just state what the connection does and how you handle the data.
Acknowledgments
Just like the README, include a quick section in your top level about code you used made by someone else (outside of the project). Of course frameworks and cocoapods can be left out as they are very clearly not your’s, but if you got a significant functionality from StackOverflow mention where it’s from.
Other scripts or methods
If you used any scripts, applications, or resources (other than those already documented), link to them in your top level to make your life easier. This could include apps like MakeAppIcon to resize app icons, Sketch for designs, or OneSignal for push notifications. It could also be scripts like ones to generate configuration files or to test feature sets.
Style explanations
If the code follows any sort of code style, mention what was the rational behind it and how to continue to follow it. This is great if you are using a linter like eslint, as the file you use to configure it will enforce project global coding styles. Mention that you use eslint and the config file is called “…”, and that coders should use eslint to stay consistent, etc.
Examples
If you are looking for some examples of excellent code documentation, there are some very exhaustive ones here:
Here is some of my documentation, in case your’e interested:
Final words:
Documentation should be just as much of a living and breathing being as your project. It’s not just something we write at the end of our time working on something, it should grow and be refined constantly. It may take some time to get started, but it will be worth it. Your work can make the difference between a good and bad hire, between buggy and smooth performance, and even between superior and inferior customer support.
