DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports Events Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones AWS Cloud
by AWS Developer Relations
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones
AWS Cloud
by AWS Developer Relations
The Latest "Software Integration: The Intersection of APIs, Microservices, and Cloud-Based Systems" Trend Report
Get the report
  1. DZone
  2. Testing, Deployment, and Maintenance
  3. Maintenance
  4. Multiplying Software Quality Using Three Documentation Types

Multiplying Software Quality Using Three Documentation Types

Documentation is vital in any software development. In this video tutorial, learn three documentation types that are crucial to a source repository.

Otavio Santana user avatar by
Otavio Santana
CORE ·
Feb. 10, 23 · Tutorial
Like (1)
Save
Tweet
Share
4.18K Views

Join the DZone community and get the full member experience.

Join For Free

You know that documentation is crucial in any software development, mainly because it increases the quality, decreases the number of meetings, and makes the team more scalable. The question is how to start a new repository or a non-documentation project. This project will clarify how to start documentation in a regular source code repository.

The documentation on the source repository applies as tactical documentation. There are also strategic ones that cover the architecture, such as the C4 model, tech radar, and architecture decision record (ADR), which we won't cover in this tutorial. 

Before starting, we'll use AsciiDoc instead of Markdown. AsciiDoc has several features to reduce the boilerplate and has more capabilities than Markdown. Furthermore, AsciiDoc has support for most Markdown syntax; thus, it will be smooth to use and migrate to Asciidoc.

README

The README file is onboard any Git repository. That is the first contact of a developer on the source code. This file must have a brief context, such as:

  • An introductory paragraph explaining why the repository exists
  • The goal of bullets
  • A Getting Started section of the repository and How To Install (i.e., in a Maven repository project, you can add the Maven dependency.
  • A highlight of the API
Markdown
 
= Project Name
:toc: auto

== Introduction

A paragraph that explains the "why" or reason for this project exists.

== Goals

* The goals on bullets
* The second goal

== Getting Started

Your reader gets into here; they need to know how to use and install it.

== The API overview

The coolest features here

== To know more

More references such as books, articles, videos, and so on.


== Samples

* https://github.com/spring-projects/spring-data-commons[Spring data commons]
* https://github.com/eclipse/jnosql[JNoSQL]
* https://github.com/xmolecules/jmolecules[jmolecules]


We have our first file and the overview of the project, what I can and cannot do, and the next step is going to the historical moment of the project and what was released on any version in our subsequent documentation.

Changelog

We can make an analogy with each version. The changelog has all the notable changes in a single file, starting with the latest version; thus, the developer knows what has changed on each version. The main goal is to be easier than Git history. Accordingly, it should have the crucial moments of each performance.

Briefly, each version has the date and the version number, plus categories of changes such as added, changed, fixed, and removed. The source code below shows a case.

Markdown
 
= Changelog
:toc: auto

All notable changes to this project will be documented in this file.

The format is based on https://keepachangelog.com/en/1.0.0/[Keep a Changelog],
and this project adheres to https://semver.org/spec/v2.0.0.html[Semantic Versioning].

== [Unreleased]

=== Added
- Create

=== Changed

- Changed

=== Removed

- Remove

=== Fixed
- Ops, fixed

== [old-version] - 2022-08-04


Great! Now, anyone in the team can see the changes by version and what the source repository does without going to several meetings or spending time to find the proposal of this repository. Whereas those types are outside the code, let's go deep inside the code.

Code Documentation

Yes, documentation inside the code helps the maintainability of any software. It is worth mentioning as many as possible. It is mainly to destroy the idea of a self-documenting code because it is a utopia in the IT area. You can do both good code, good documentation, and a test that helps with documentation.

You can explore the source code to be complementary, explain the code design's why, and bring the business context to the code. Remember, the tests also help with documentation. 

Please, don't use the source code to explain documentation. It is a waste of documentation and a bad practice.

On Java, you can explore the Javadoc capabilities; if you are not, don't worry about which language has a specific tool for it.

Conclusion

This article explains three documentation types to start a regular source code repository. Please, be aware it is a start, and documentation may vary with the code project, such as OpenAPI with Swagger when we talk about REST API.

Documentation is crucial, and we can see several colossal software such as open-source projects like Java, Linux, Go, etc., have documentation. Indeed, with several projects, proposals, languages, and architectural styles, documentation as the first citizen is the expected behavior among them. 

I hope you understand how meaningful documentation is and good codes, and I hope that you make your and your company simpler with more documentation in the source code repository.


Documentation Software development Software quality

Opinions expressed by DZone contributors are their own.

Popular on DZone

  • Container Security: Don't Let Your Guard Down
  • Master Spring Boot 3 With GraalVM Native Image
  • Use AWS Controllers for Kubernetes To Deploy a Serverless Data Processing Solution With SQS, Lambda, and DynamoDB
  • 10 Most Popular Frameworks for Building RESTful APIs

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com
  • +1 (919) 678-0300

Let's be friends: