Write the Technical Documentation for Your Project

In the previous chapter, you saw the best practices to use in documenting your code.

In this chapter, you will learn how to publish your documentation online with GitHub and Read the Docs.

Use Git Like a Pro!

Why Manage Code With Git?

As you probably know, Git is a version control system for code, making it easier to work with other people on a team.

Get the Most Out of Git

As mentioned, each change (addition, deletion, etc.) is accompanied by a message when you commit your code. This message is not optional, and you need to be very careful about how you write it.

These messages make up a history, which allows you to go back through all your decisions and changes to the code at a glance.

For example, when merging with another branch:

Merge branch 'java/addproduct' into main

Or to describe a feature:

feature: used to add a product to the shopping cart

README, a Window to Your Project

README files provide a quick overview of the aim and context of the work for contributors or visitors to the project.

Here are some suggestions to include in your README files:

• You can use badges (such as For The Badge or Shields) to label your project easily and show its status or progress.

• A title and a quick explanatory header, perhaps with a snapshot, are essential. 

• The team working on the project.

• The technology used.

• Licensing aspects.

• How to contribute if it’s an open-source project.

This isn’t an exhaustive list, but these are the essential basics.

Before finishing this chapter, here’s a model README file that you can use for your code projects. It’s based on a hypothetical project for an alarm clock app and contains all of the above information.

[![forthebadge](https://forthebadge.com/images/badges/cc-0.svg)](https://forthebadge.com) [![forthebadge](https://forthebadge.com/images/badges/made-with-javascript.svg)](https://forthebadge.com) [![forthebadge](https://forthebadge.com/images/badges/uses-css.svg)](https://forthebadge.com)

# Sleep Well : the smart alarm-clock app

Sleep Well aims at developing a smart alarm clock for iPhones that monitors your breathing rhythm while you sleep to determine your sleep cycles.

## Technologies
- JS
- CSS
- React

## Contribute to the project

Sleep Well is an open source project. Feel free to fork the source and contribute with your own features.

## Authors

Our code squad : Francis & Stéphane

## Licensing

This project was built under the Creative Commons license.

Here’s the result in my repository:

Now you've seen how to use Git for effective documentation; you're going to learn about Read the Docs, a very widely-used tool in the development world, which you can sync with Git to improve teamwork on your documentation. 

Read the Docs

This means that you can create, test, and update your documentation with every commit.

Without going into too much detail, Read the Docs works based on the following:

• Sphinx is one of the Python community tools for generating documentation.

• reStructuredText is a language similar to Markdown that allows you to write code documentation in full text. 

Here’s an example of  reStructuredText  syntax:

Sleep Well Documentation
========================
:Author: Francis
:Version: $1.0$
:License: Creative Commons

Contents
------------

This documentation highlights the most important elements to **install** and to **configure** your app.

Technologies
------------

* JS
* CSS
* HMTL

Installing the app
------------------

...

And here’s the result with a classic reStructuredText editor:

Within this ecosystem, Read the Docs allows you to link Sphinx to Git, providing you with version control, full-text search, and all the Git features. As a developer on a team, combining two tools provides you with a powerful toolkit for you and your team to work on documentation.

On a technical level, linking your Read the Docs account to a Git repository allows you to:

• Clone the repository.

• Create documentation for the master branch in HTML and PDF format.

• Index documentation to allow full-text searches.

• Create documentation branches if necessary.

Let’s Recap!

In this chapter, you saw that:

• Following a few rules for writing commits and using a coherent README helps you get the most out of Git and your documentation. 

• Linking your repository with a tool such as Read the Docs further improves this ecosystem by providing you with a set of very powerful tools for working as part of a team.

In this chapter, you saw how to get the most out of the tools available to work efficiently on a team and publish your documentation online. 

In the last chapter of this part, you will learn how to design professional API documentation.