DPS909/OSD600 Fall 2017 Lab 9
Introduction: Documenting Open Source
In this lab we will explore different techniques for documenting an open source project. One of the goals will be to learn more about authoring Markdown, as well as other areas where good documentation helps a project gain users and developers.
A big part of creating and maintaining an open source project is writing good documentation. There are many levels of documentation that people need, for example:
- code comments: to explain design decisions, why certain choices were made (e.g., edge cases), references to other parts of the code or other projects.
- README.md: to give users information on how to install and use a project, define APIs and the options one can use, give short examples. See https://guides.github.com/features/wikis/#creating-a-readme
- CONTRIBUTING.md: to give developers information on how to contribute fixes or new code to the project, including info on how to setup the environment, how to run tests, coding conventions, etc.
- CODE_OF_CONDUCT.md: a recent practice aimed at helping to establish norms and expectations for everyone in a project. See https://opensource.guide/code-of-conduct/ for more info.
- examples/: a directory with example code to show how one might accomplish common tasks using the project
- wikis: a place to put various types of other documentation, from help docs to sample code to instructions for doing various development/coding tasks. See https://guides.github.com/features/wikis/#creating-your-wiki
- tests/: test code is often surprisingly good at also serving as technical documentation. When developers write tests, they are also communicating how they think their code should work, how APIs can be called, etc. Having good tests means also get some documentation for free.
In this lab, you will add documentation for your project from the code you wrote in Labs 6, 7, and 8.
Step 1. Add a README.md
GitHub will automatically render any Markdown (.md) it finds in a repo.
Start by reviewing GitHub's Markdown Guide, and familiarizing yourself with the various ways to do things in Markdown (e.g., links, images, lists, source code highlighting, etc.)
Next, create a README.md file in the root of your project, and start documenting your project. You should take a look at some good READMEs for ideas on how to structure yours. Also, checkout READMEs for projects written in the same language as your code, to get ideas on how people tend to document things in language X.
Here are some ideas to include:
- Project title
- Build status (e.g., see https://docs.travis-ci.com/user/status-images/)
- Clear description of what it is, what it does, and if necessary what it isn't
- Images, if applicable (e.g., screenshot, logo)
- Table of contents, with links to different sections, so it's fast to jump around
- Installation instructions for different environments
- API documentation
- Example code
- FAQ, if necessary
There's no one right way to do this, and not every README needs to include everything.
Create your README.md file, add it to your repo, and push it up to GitHub.
Step 2. Add code comments
Audit your code (go back and read it all) and see where you need to add comments. There are a few types to consider:
- Comments to explain tricky bits of code, or why you decided to do something the way you did. If the code is self-explanatory, then it won't need a comment. If you have to think about it for a bit, you might consider adding a comment.
- Comments above functions, classes, etc. that provide API level docs. These could be in JavaDoc style, or whatever style your language uses for doing higher-level documentation embedded in your code. Here you can document function arguments and return types, possible error cases, and the purpose of APIs in general.
- TODO, HACK, XXX style comments help to point out places in the code where you know you have technical debt, and need to return and fix something later. Even better would be a bug you might file and then link to it in the comments.
- Any code you've borrowed from another project should be commented, and a link to the original and its license.
Make sure that your code is maintainable by you and others, and include enough documentation in the code to make it easy to understand. Always favour clarity over complexity, and be explicit vs. assuming too much prior knowledge. Imagine if you have to fix this code a year from now, what will you wish you still knew? Document that!
Step 3. Examples/ code
Add some example code to show people how to use your API. This can be different than a unit test, since you are showing a more real-world use case of how to interact with your code. You are trying to make it clear to someone looking at your code for the first time how they might use it. If there are common ways people will want to do that, add examples here. You don't have to jam everything into one example and over-complicate it. Do lots of little ones if that makes it easier.
Make sure you include links from your README to your examples/ code, so that people can find it easily.
Step 4. Get your docs reviewed
Ask another student in the class to review your project's documentation. Get them to look at everything you wrote above, and any other docs you decide to add, and see what suggestions they make. Fix any issues they find in your docs.
Submission
Please add your info to the table below. Include a blog post about the process above, what you learned, what you found interesting/new, what you got stuck on or found hard, and any other ideas you might have had while doing this. Did you know about Markdown before? What about the other forms of documentation? Are there any projects on GitHub you found that you thought were well documented? Why? What did your reviewer suggest when he/she looked at your docs?