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
Please enter at least three characters to search
Refcards Trend Reports
Events Video Library
Refcards
Trend Reports

Events

View Events Video Library

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
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

Modernize your data layer. Learn how to design cloud-native database architectures to meet the evolving demands of AI and GenAI workkloads.

Secure your stack and shape the future! Help dev teams across the globe navigate their software supply chain security challenges.

Releasing software shouldn't be stressful or risky. Learn how to leverage progressive delivery techniques to ensure safer deployments.

Avoid machine learning mistakes and boost model performance! Discover key ML patterns, anti-patterns, data strategies, and more.

Related

  • Google Cloud Document AI Basics
  • The Rise of Shadow AI: When Innovation Outpaces Governance
  • Thumbnail Generator Microservice for PDF in Spring Boot
  • Build a Local AI-Powered Document Summarization Tool

Trending

  • Develop a Reverse Proxy With Caching in Go
  • It’s Not About Control — It’s About Collaboration Between Architecture and Security
  • Hybrid Cloud vs Multi-Cloud: Choosing the Right Strategy for AI Scalability and Security
  • Beyond Linguistics: Real-Time Domain Event Mapping with WebSocket and Spring Boot

Don't Underestimate Documentation

Documentation is crucial to development processes and brings many benefits to development delivery. Let's look at some recommendations and tools for Java-based projects.

By 
Dmitry Egorov user avatar
Dmitry Egorov
DZone Core CORE ·
Updated May. 11, 22 · Opinion
Likes (8)
Comment
Save
Tweet
Share
8.3K Views

Join the DZone community and get the full member experience.

Join For Free

Documentation Sounds Like an Annoying, Boring Thing

Maybe you feel that documenting the project or your code is an extra annoying step. Often, documentation for projects is outdated and irrelevant. In such cases, most of the expertise is hidden in analysts or just developers. In this article I'll try to explain why having a good documentation culture will make projects much more stable and successful.

systems + documentation = good ideas

Writing Good Documentation Often Makes a Big Difference

There is no specific rule on how to make perfect documentation, but obviously plain text without details is much worse than documentation with screenshots, diagrams, and images. It takes time to write a quality manual, but it's worth it because it solves many problems at once, including slow onboarding processes, slow communication, single-person projects, and lack of team support. 

Onboarding Process Improvement

Often when documentation is outdated or doesn't exist, new employees have to ask too many silly questions and waste senior players' time. In the case of rich documentation, new devs will learn the vast majority of the project logic all alone. Also, the process of learning the project will be shortened and new employers won't be that dependent on the existing team

onboarding time is significantly reduced

Faster Communication 

Having well-documented features means you don't need to explain the same thing again and again — all you have to do is give a link to the documentation. Also, the document itself might be a good place for discussion or a place for potential improvements.

Fast team communication

Removing the Single Person Project Curse

Have you ever seen a project that is mainly maintained by one person? Then you might have seen how their project dies when they leave the company. The best way to avoid such scenarios is to ask this person to document the project from A to Z. Unfortunately, such situations are intentionally created, and such "one-person projects" have no documentation because this one person wants everyone to depend on them. Forcing them to make documentation will solve this problem and remove the risk.

The curse of only one man being the source of info

A Support Team Means a Stressless Life

In cases when production is supported by a dedicated team, proper up-to-date documentation might be priceless. For a production issue, the support team might fix the problem without waiting for the development team.

support teams make life easier

Create a Workshop to Share Documentation About Your Feature

After each sprint/iteration, it's very useful not just to share how your feature works but also to show how it works by providing a recently created manual. Having such practices, a team will:

  • Build a proper documentation culture
  • Make documentation standardized
  • Be assured that all new features are well covered by the documentation

documentation graphic

Sady, such practices almost don't exist in real life, but I would recommend integrating such events. You'll see that the confidence of each team player will grow. 

Obvious Documentation Recommendations

In order to keep documentation readable and maintainable, please follow these instructions:

  • Provide more screenshots and images
  • Make more diagrams (for example, draw.io)
  • Keep it simple and easy to read like you've been doing for yourself
  • Follow the same style convention

Where to Keep Documentation 

If we are talking about documenting source code, there are two ways to store documentation:

  • Rich README file right inside the project (became more and more popular because it reduces the distance between developer and documentation)
  • Confluence pages or any other documentation framework. This option is more useful especially when the team has not only developers but testers and analysts. 

Personally, I prefer any web pages instead of some README.md files because webpages are much more flexible and have more potential features.

Documentation Tools

Depending on the project, there are many tools that can be used. Some general tools that I recommend include:

  • draw.io has many features that allow you to picture your project with its dependencies. 
  • Markdown is a format that allows you to make your README files much more visible.
  • Confluence is a paid but popular solution for documenting anything. It integrates with many tools including draw.io. For small teams, it is very affordable.

If we talk about code tools specifically for code documenting then next tools can be used:

  • JavaDocs generator from IDEA
  • The REST API generator Swagger. Swagger allows you to generate documentation and live examples for each API call. This tool is a "must-have" and became the enterprise development standard
  • The REST API generator from Spring. It's also a Swagger version but embedded right inside Spring Framework
  • Docs generator for GRPC protocol
  • Class visualizer, which shows images with class structure. Such a tool would be used by developers and no one else. Just simplify the process of reading the code.

If these aren't what you're looking for, here are some alternative documentation writing tools.

Self-Documented Code: Alternative to Documentation?

Maybe you have heard about such things as self-documented code. What is it? Well, it's a set of conventions and rules for how code has to be written. For example:

  • All classes have to start with a capital letter. For example, User
  • All final content fields have to be written in capital letters with an underscore between words. For example, THIS_IS_THE_FINAL_VARIABLE
  • All variables have to start with lowercase and be in camel case. For example, usersDetailsVariable

Well, does it actually document anything? No. It's a different thing, but in general, code conventions lead to code visibility and make it much easier to read. So in some sense, self-documentation solves the same problems as simple documentation.

Who Has to Write Documentation?  

Everyone has to write documentation and clarify moments related to their own functionality. Developers can explain what code is responsible for which feature. Managers can explain business aspects. Web designers can clarify UX importance moments. But in practice and in most cases, developers are too lazy to document anything and avoid it. So analysts and managers are doing that job quite often. But analysts or managers can't document code-related things and, in the end, such documentation is not usable for developers. So as a result, such documentation is useful only for analysts and managers. 

The Final Message: Documentation Is Important

Well, there is not much to add. I hope I've provided why you better write good documentation and keep it up to date. This is a lesson I learned while working on many projects for more than ten years. Especially in big and slow companies, missing documentation will cost a lot from a time and performance perspective. So, having a habit to write docs about the feature you have implemented will help you and everyone on the team.

Diagram of how documentation helps

Document IT

Opinions expressed by DZone contributors are their own.

Related

  • Google Cloud Document AI Basics
  • The Rise of Shadow AI: When Innovation Outpaces Governance
  • Thumbnail Generator Microservice for PDF in Spring Boot
  • Build a Local AI-Powered Document Summarization Tool

Partner Resources

×

Comments
Oops! Something Went Wrong

The likes didn't load as expected. Please refresh the page and try again.

ABOUT US

  • About DZone
  • Support and feedback
  • Community research
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

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

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • support@dzone.com

Let's be friends:

Likes
There are no likes...yet! 👀
Be the first to like this post!
It looks like you're not logged in.
Sign in to see who liked this post!