Documentation — What Is Still Missing In Your Project Docs (Front-end Developer’s Perspective)

In the front-end world, we often find ourselves working on internal projects or products where documentation is either nonexistent or lacking crucial information. It’s a familiar scenario that can hinder productivity and cause frustration. Even if documentation exists, writing documentation continuously in real-time can be challenging for teams. It can easily become outdated, as it is often unclear when and how to update it.

Illustration: Wioleta Zamrzycka

However, when we venture into the realm of open-source projects, the landscape changes significantly. Here, we discover a wealth of comprehensive documentation that serves as a valuable resource for understanding library usage. In this article, I aim to delve into the significance of internal project documentation and share my perspective as a developer on the essential elements I frequently seek in front-end project documentation.

Why Do We Need Docs?

Let’s get straight to the point. Front-end developers often overlook the importance of documentation, which can lead to several challenges, such as:

• Introducing a new team member to the project becomes difficult when documentation is lacking.
• Handing over the project to another team becomes a daunting task without proper documentation.
• Implementing significant changes in the project becomes risky without a clear understanding of the potential impacts on different parts of the codebase.
• Documentation can become outdated over time, leading to misunderstandings.
• Often, there is no clear responsibility for handling the documentation. If no one is specifically assigned to it, nobody feels responsible for maintaining it.
• Documentation is often scattered across various platforms, making it difficult to find useful information.

While, on the other hand, not having documentation enables faster delivery of solutions as there is no need for continuous updates. However, is this a sufficient reason to avoid writing documentation? Similarly, many teams skip writing automated tests to speed up delivery. Unfortunately, this practice results in regression and sanity testing for each new release in the production environment.

Consider Who You’re Doing It For

We can treat documentation as a product. Every product should have a target audience — someone who finds it useful and would be willing to pay for it. While we don’t charge money for documentation, we can consider the time someone invests in reading it and the potential recognition we receive as compensation. Creating user personas can help us understand better who we are writing for and to plan the content accordingly.

Don’t forget that you are also an important customer of the documentation you write. Often, after just a month, we forget the details of the code we wrote not so long ago. Writing documentation is a way to address this, as whenever a problem arises with previously delivered functionality, you can save a lot of time by referring to the documentation and understanding what you meant and why you did it that way.

Illustration: Wioleta Zamrzycka

Where Should You Write It?

Before starting to write, consider the existing situation within the company.

Do we have any established standards or tools that we should utilize, or do we have the freedom to choose?

The type of documentation we write and the target audience can influence where we decide to place our documentation. For example, if it is technical documentation strictly related to the project, it might be best to keep it close to the code. You can use rich text editors like Notion, GitHub Wiki, or Confluence. For technical documentation closely tied to the project’s codebase, it might be beneficial to keep the documentation in close proximity to the code itself. The markdown can be a suitable choice for such documentation, as it allows us to include code snippets, images, and various text formatting options.

Another aspect worth considering is whether the documentation will be easy to find for potential parties involved. Usually, documentation should be placed where there is a chance of it being discovered. If it is technical documentation related to a web project, is there a better place to reach other programmers than putting it in a repository?

We often come across technical documents placed in a shared space for the entire company, such as Confluence. If you work in a large organization, the number of documents in such a space is usually immense, making it increasingly difficult to navigate and find what you’re looking for. This can be a significant problem, especially when the documents in such a space are not well-organized.

There is also the possibility of using more than one platform for documentation. This can have significant advantages. Let’s consider the need to make an important decision regarding project architecture, for which we will need input from members of other teams. In such a case, we can write a Technical Design Document (TDD), invite other developers for a review, and once we have considered the comments and feedback, we can document the final decision close to the code, in the repository, for easy accessibility. The TDD can serve as an archive describing the problem in-depth and the options we considered, while the repository documentation can serve as the ultimate source of knowledge. It is worth including a link to the TDD in the repository documentation, creating a natural connection between the two documents.

What Have We Done?

In SwingDev, I am part of a team working on a platform for our parent company’s customers. As we were writing documentation for a front-end project targeting developers, we used Markdown, which allowed us to achieve everything we needed. We write docs for us and other developers, and in the future, we plan to hand over the project to another team, which prompted us to examine our approach.

In the main README.md file, besides the application name, we decided to include only links to more specific subpages. We divided the documentation into the following main sections:

• Getting Started: Here, we describe the project from a business perspective, including its objectives, goals, and target audience. We provide information about available environments, URLs, and ways to log into the application.
• Development: This section covers hardware and software requirements, how to start the project, and the main scripts involved. We also discuss our approach to component and code testing. Additionally, we include a subsection called “Documentation” that addresses when to update the docs and what information should be included. To quote from the documentation:

The project documentation should be a dynamic and constantly evolving resource. It should be consistently updated and revised to reflect any changes or new conventions that are introduced. When considering whether to add something to our documentation on GitHub, we should ask ourselves, ‘Should this be included?’ 🤔

Not everything needs to be added to the project documentation. However, there are certain situations where it is important to consider making changes.

In addition to documenting our code through the project documentation, we should also utilize comments within the code itself. This is especially useful for explaining more complex sections of code that require additional information or context. While having well-organized and clear code is important, sometimes it is necessary to provide explanations as to why certain decisions were made. The code itself becomes the best place to leave this additional information.

• Pull Requests: We define our branch naming convention, commit message convention, and the requirements that a pull request must fulfill to be merged. We also mention the inclusion of a GitHub pull request template, which is valuable to have in the repository as it enables the automated creation of pull requests.
• Releases: This section describes how the product is released, including the frequency and the specific steps required to release a new feature.
• Flows: In this section, we aim to explain more complex topics that require detailed explanations beyond what can be provided in code comments. In our case, this includes topics such as authentication, GraphQL workflow, and testing CORS features.
• Decisions: Here, we include all technical decisions specifically related to the project. This serves as our point of reference in case of any doubts. It acts as our source of truth. If there was a Technical Design Document (TDD) where we considered alternative options, we include a link to that document.

Test Before You Announce the End of Work

As someone familiar with the project, it may be challenging for you to assess whether what you have written is sufficient and fulfilling its purpose. To overcome this, invite another person who matches the defined user personas. Ask them to attempt setting up the project, creating an account, etc. Check if they can find the documentation and determine if you have provided clear instructions on where and how to access it.

Observe how they use the documentation and assess whether they can find the information they need. Pose a question for which the answer is present in the documentation, and verify if they can locate it successfully. This testing process will help identify any gaps or areas for improvement in your documentation.

The process that never ends

Okay, you’ve finished writing the project documentation. In your opinion, it already contains all the possible details about the project that may be important for you or other developers in the future. That’s great! However, I have some bad news for you — your work is not done. In order for your documentation to be valuable, it needs to be regularly updated. The more documents it contains, the more likely it is to become outdated.

So, how can you enforce documenting changes in the project?

Following the principle that if no one is assigned to a task, it’s likely that no one will take care of it, you can designate a person responsible for overseeing and reminding others about documentation. This can be the team leader or a technical project manager. This simple solution ensures that the documentation will be kept up to date to a great extent.

Another possible solution to the problem is to plan regular documentation reviews, during which you assess its relevance and make necessary updates. It’s important to establish suitable intervals, such as quarterly, to ensure that the documentation aligns with the current state of the project.

Also, remember that you can remove outdated content. A leaner documentation increases the chances of it being updated.

By adopting these practices, you can ensure that your documentation remains valuable and reflects the evolving nature of the project. The process of maintaining and updating documentation should be seen as an ongoing effort rather than a one-time task.

Conclusion

Documentation plays a crucial role, and as front-end developers, we need to ensure that our project documentation is comprehensive and valuable. By examining the various aspects of documentation, we can draw some important conclusions:

• Documentation is essential for effective knowledge transfer: Whether it’s introducing a new team member to the project or handing it over to another team, well-documented code, and clear instructions make the onboarding process smoother and minimize the risk of misinterpretation.
• Documentation improves project scalability and maintainability: When we encounter the need for significant changes or updates in the project, comprehensive documentation allows us to understand the system’s intricacies and make informed decisions. It enables us to assess potential impacts on various components and make adjustments accordingly.
• Consider documentation as a valuable product: Treating documentation as a product means understanding its value to the audience. By creating user personas, we can better identify the needs and expectations of our readers, enabling us to tailor the documentation to their requirements.
• Choose the right location and format: Depending on the nature of the documentation and its intended audience, we should select an appropriate location and format. A markdown is a versatile option for technical documentation, allowing us to include code snippets, images, and formatting options.
• Regularly test and iterate: Testing the effectiveness of our documentation is essential. By involving someone from our target audience, we can assess the accessibility and usability of the documentation. Their feedback will help us identify areas for improvement and ensure that the documentation meets the needs of our users.

By dedicating time and effort to write comprehensive documentation, we empower ourselves and others to work efficiently and effectively within the project. And remember that documentation is not just a means to an end but a valuable asset that contributes to the success of our projects.

If this article has been interesting to you, we encourage you to explore career opportunities at SwingDev 🚀