The path to a useful and maintainable frontend documentation

How to make sure your code will survive the years to come

Motivation

Througout many projects with different colleagues we have come to realize that software maintanance and longevity is a huge part of IT development.
Many companies hire amazing talent and spend great budgets in order to develop software solutions. But after a while they realize that development cycles for new features and bug fixes begin to increase massively.
Now how is longevity of software not obvious?
Well it all comes down to time vs. quality. While most software engineers try to make sure their code is maintainable and useful — they tend to skip quality aspects due to timing pressure of upper management.
The quality aspect of code documentation suffers massively and leads to a huge knowledge gap for new team members.
This article aims to show you my approach for a useful frontend documentation and how we are making sure that it is valuable.

What is good frontend documentation?

Software documentation refers to all the documents, images and material in general that describes the development, functionality and the use of software.
The purpose is simple —help everyone understand your code and product.
In frontend projects a good documentation needs to include the following:

1. Explain the product
   What does the product do? Who is using it?
   Use screenshots if possible and show each view.
2. List the technologies
   Make it easy to understand what your team is using. If you can also backup your technology decisions, management will thank you.
3. Expound on integration
   Where does the frontend run? How is it integrated into other software?
4. Show the application architecture
   Try to create a diagram of the components and views.
   Click here for an approach to frontend architecture.
5. Explain the API and backend communication
   Make sure a reader knows where the data is coming from.
6. Start with the folder structure
   Show screenshots and explain the folders in your project. Elaborate which files are where and what type of functionality the folder represents.
7. Explain the types of objects
   Modules, components, services, reducers…anything you use should have a spot in your documentation. Underline their use case and use examples.
8. Emphasize important modules and routes
   Make sure the reader knows where to find each view and what functionality is encompassed by which module.
9. Show your testing approach
   Explain how you test, where the tests are and important aspects.
10. Frequently asked questions
    Add everything a new reader asks you.

Documentation tools and location

I believe the tools are not as important as the decision to update documentation on a regular base. Whether you are using a confluence document, google drive, Readme.md or docusaurus, it truly is more about the constant updates.
We use .md as a format and include the documentation usually in the project itself. This decision was made because of the higher chance of it being found, used and updated.
I am sure you have heard it already— but great developers are lazy.
And that is good. So why not make our lives easier by putting the documentation into the project? Furthermore — this way the screenshots, components and any resource needed is already located in the same directory.

Documentation Example

Product
The product is a todo management app that is used by our employees to write down their todos on a daily basis. They can enter todos and mark them as done.

Screenshots

source: todoist.com

Technologies
TypeScript, React, Redux, scss, styled components, axios, npm, webpack, cypress

Integration
The web app runs on its own node server on a linux machine.

Backend API
There is no backend since the tasks are on a daily basis.

Folder Structure

todo
│ ───package.json # npm dependencies and run scripts
│ ───Readme.md # Documentation
│───index.html # Entry point of application
│ ───app # Main application folder
│ ├───app.scss # Application stylesheet
│ ├───app.tsx # App component
│ │───index.tsx #React starting point
│ ├───routes.tsx # Router for views
│ ├───components # UI Components used
│ │ ├───todoButton # Markable todo list element
│ │ │ └───…
│ ├───config #Application configuration files
│ ├───modules
│ │ ├───listTodos # View for todo list for today
│ │ ├───createTodo # View for todo creation
│ ├───services # Data manipulation
│ └───shared # Models, reducers and util
│ │ ├───model
│ │ ├───reducers
│ │ └───util
│ ├───content # Static assets like images and fonts
│ ├───cypress # Cypress tests
│ ├───doc # Documentation data
│ ├───i18n # Internationalization
│ ├───node_modules # Dependencies

Architecture and Types of Objects
Click here for an approach to architecture.

Summary

Documentation is key when it comes to longevity and maintanance of software projects. To make sure your software continues to grow and work — developers need to provide new developers with resources.
I hope this article could provide you with an overview of what should be included in a modern frontend application.
Thanks for reading!

Curious about more?

My newsletter is a burst of tech inspiration, problem-solving hacks, and entrepreneurial spirit.
Subscribe for your weekly dose of innovation and mind-freeing insights:
https://davidthetechie.substack.com/