About This Course
I’m Max Wardeh, an educator and consultant, and I’m looking forward to guiding you through this course on documenting your code projects.
This course is for developers and software architects of all levels who want to learn to produce better documentation to ensure their personal or professional project code can be reused and maintained.
First, a few words on the structure of this course so that you can get the most out of it while working independently.
In each chapter, I’ll explain the concepts in detail and help you put them into practice.
Finally, you can use the quizzes (one for each part) to test your knowledge.
Part 1 is mainly aimed at developers and focuses on the best practices for writing documentation to make your code easy to reuse and maintain.
Part 2 is mainly directed at software architects and deals with the technical aspects of documentation for architecture projects.
Why Write Documentation?
Document Your Projects to Save Time and Create Consistency
If your project documentation is incomplete (or doesn’t exist), different stakeholders could understand it differently, leading to incorrect interpretations of the solution. As a result, some stakeholders may take the project in the wrong direction and have to backtrack later. This wastes time and resources and can hurt team morale.
Likewise, non-existent or incomplete documentation will mean that you’ll have to describe the solution repeatedly to each new team member and external contractor. Here too, documentation helps you save time and ensure a degree of consistency.
Document Your Projects to Make Your Code Easy to Read and Maintain
When working on a project as part of a team, as you’ve probably already done or will do in the future, you can’t afford to slow down or get stuck due to poorly written or formatted code.
Working on a team means making many different changes to the code, and poor code readability will cause the team’s productivity to decline. This is an untenable situation over the long term. For this reason, your code should be formatted, written, and documented according to shared rules, which will help all new members understand the team’s requirements.
The Cost of Undocumented Code
Hopefully, after reading the previous paragraph, you can see why the quality of your code and documentation significantly impacts a team’s productivity. Another thing to be aware of is that the longer such a situation goes on, the more it costs to restore order. The sooner you document your code, the easier and quicker it is.
Adopt the Right Attitude to Documentation
Writing documentation is important, but it’s also vital to have the right attitude when working on code projects. Here are a few initial concepts, which we’ll look at in more detail later in the course.
Code For the Team
The first essential attitude is that you should code for the team, not yourself. This is why you need to be strict with your developments and documentation, to make sure everyone can understand them.
Balance Quantity and Quality
Having the right attitude also means finding a compromise between quality and quantity regarding the cost that documentation represents. Don’t forget that writing documentation and correctly formatted code takes time and costs money! It’s your job to find the right balance using the tools and examples provided in this course.
Maintain Your Documentation
Finally, it’s not enough to write well—you also have to keep your documentation in order over time. It means you need to maintain your documentation and update it regularly, just like your code. You could even aim to improve readability over time. This is the mark of a true professional!
Let’s Recap!
Good and comprehensive documentation:
Provides better consistency, especially in a shared environment.
Makes for more readable and maintainable code.
Helps you save time by cutting costs linked to corrections.
Means adopting a professional attitude, which benefits the team by balancing quality and quantity.
Now you’ve got a good idea of what to expect in this course and the main issues linked to documentation; it’s time to take a closer look at how to write project documentation to get the most out of it. That’s what we’re going to do in the next chapter!
Are you ready? Then let’s go to the next chapter right away!
