Just like revision control best practices would be meaningless without a revision control tool like git, design best practices are meaningless without a tool to help you track your design documents.

Okay, that isn't quite accurate, but it's inaccuracy is the root of why design tools have languished so much. It is easy to think that your requirements can be completely captured in your README, or in code documentation, or in unit tests -- but in the end they get captured everywhere and nowhere. You end up either repeating intention or forgetting to specify it all together.

Let's get this out of the way first: except for some of the simplest libraries, developer documents should not be your only design documents! The things your users are concerned about should almost never be the implementation details or architecture of your project, and unless your library is so simple that all design decisions fit in a few sentences, your code documentation won't cut it for preserving intent or pointing out the relationships between components.

This is not to say that user (README) and developer (code) documentation are not critical to a project's quality: they absolutely are. But they should not replace your requirements, detailed-design or testing documents for any but the simplest projects.

Keep in mind that it is always best practice to try and split your project into as many small libraries as possible. Simplicity should always be the number one goal. However, not all applications and libraries can be made so simple, and even in such cases you still might want an overall architecture for how to achieve such simplicity.

So, here are the primary tools that every developer should have under their belt to increase the quality of their software and their productivity.

This is probably the most essential tool to learn how to use, as it allows you to code fearlessly without worrying that past efforts will be lost. We will be using git in this tutorial to track our progress at each stage.

Most languages can take inline documentation on your functions, classes, etc and translate them into rendered and beautiful user docs. Some languages support it natively, others require a separate library.

We will be writing python documentation can be natively viewed on the REPL by calling help(obj) and could be converted using Spinx.

Almost every language has a unit testing framework. Get to know yours intimately. We will be using python's unittest package to write tests in this tutorial and pytest to run them.

When all code is automatically formatted and linted, it is easier to read and edit. Also, arguing over whether to use tabs or spaces is probably the least productive thing possible. Use the default formatters and linters for your language, it is an easy way to make your code cleaner and simpler.

We will install these in a later chapter.

Some people believe that the primary responsibility of Software Engineers in Test (my job title) is to design test cases. In my opinion, the primary job of an SET should be to develop processes, tools and frameworks that make the entire organization run more efficiently, more simply and with higher quality.

This section will be one of the least discussed in this book, but it can be the most important for your future development. The problem is that it can't really be taught except to say: always look for ways you can automate pain points and increase simplicity. Develop tools that make it easy to interface with your product, or hook into annoying legacy test software, or develop tests in a simpler way. These tools can be a script, a new way of doing things or even just a library/module. By making everyone's life easier, you will drastically increase quality

artifact: the design doc tool made for developers

Artifact will be our bread and butter for writing and linking our design to our source code and then hosting them as a webpage. This tool was designed specifically to facilitate the philosophy of software quality presented in this book. Artifact will be the topic of the next chapter.

At the end of the process, we will be able to host our design docs just like the artifact project's design docs.

Before we do anything else, let's start using git to track our progress. Since artifact tracks design docs which are written in plain text, you can (and should) use revision control to track the evolution of your design documents.

Note: you should have already set up your project

git add README.md
git commit -m "add README.md"

This will add the progress you have made so far to git and allow us to track our progress.

Exercise 1:

git is a fantastic tool, but it is beyond the scope of this guide to give a full tutorial on git or revision control in general. Before proceeding with this guide any further, it is recommended you go through the git tutorial

You can always type git COMMAND -h to get help on any command.

The rest of the tutorial will assume you have a working knowledge of git commands and what their purpose is.