Proposal for Documentation Template for the Admin Team

[marcelovicentegc]

Proposal for Documentation Template for the Admin Team

This document aims to consolidate and formalize a documentation template for the repositories of the Admin team. This particular proposal follows the following premises:

• Documentation that is close to the code is better than documentation that is far from the code, as it facilitates the maintenance and updating of relevant information for developers.
• A behavioral change is necessary for the documentation to have an impact, regardless of its location or organization.

Documentation Structure

Each repository of the Admin team (including templates) will follow the following documentation structure:

Documentation File Structure

All documentation within the root folder:

• /README.md
• /CONTRIBUTING.md or a How to Contribute section in the README.md file
• /CHANGELOG.md or GitHub Releases
• /docs/.md (e.g., ARCHITECTURE.md, OBSERVABILITY.md, LOCALIZATION.md, CACHING.md, INTEGRATION_TESTS.md, tutorials, guides, etc.)
• Comments/jsDocs in the code when necessary
• Wiki (optional)

README.md

The /README.md file will be the entry point for the project's documentation. It should be clear and concise, providing essential information about the project, divided into three sections that define its structure:

• Overview of the project (features, usage, prerequisites, and installation)
• How to run and test
• How to contribute
• Example structure of /README/md:

# project-name

## Project Overview

### Features and Usage

### Prerequisites and Installation

## How to Run and Test

## How to Contribute

Complete example:

# admin-shell-widgets

## Project Overview

This NextJS project contains the widgets (components) that make up the VTEX Admin shell: the Sidebar (`sidebar.tsx`) and the Topbar (`topbar.tsx`), including the account switcher (`account-switcher.tsx`), the Global Search (`global-search.tsx`), the Announcements modal (`announcements.tsx`), the Help Cards (`knowledge-base.tsx`), and the Profile menu (`profile-menu.tsx`).

Under the hood, this project utilizes [Raccoon](https://github.com/vtex/raccoon), which allows integrating NextJS apps with VTEX IO. Refer to the Raccoon documentation for more details.

### Features and Usage

The project's features include rendering the Admin Sidebar and Topbar with all the relevant information for the client, such as:
- Displaying the list of installed and available modules for the client.
- Displaying the list of sub-accounts under the accessed account.
- Displaying new announcements published in the Help Center.
- Displaying articles that help the client navigate the Admin.
- Displaying the global search, allowing the user to find modules and orders.
- Changing the Admin's language.

### Prerequisites and Installation

To use this project, you should be familiar with Raccoon, React, [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), and have the `VTEX IO` CLI installed.

To install the project's dependencies, simply clone the repository and run the following command:

> yarn

## How to Run and Test

To start the project on your machine, simply run:

> yarn dev

And access the `localhost` workspace of the `teamadmin` account: https://localhost--teamadmin.myvtex.com/admin

You will see the changes made in the code reflected in the above workspace.

## How to Contribute
<!-- This section can be replaced with the CONTRIBUTING.md file -->
This project follows the semantic commit model, so ensure that your commits follow this pattern so that releases containing your changes are generated correctly.

Open a pull request once your changes are ready, and follow the instructions in the pull request template that aligns with the nature of your changes (a new feature, bug fix, or improvement).

The members of @vtex/admin will review and merge your pull request once it is approved by them.

CONTRIBUTING.md

The /CONTRIBUTING.md file or contribution section in the /README.md should describe the contribution process for the project. It should include information about:

• How to report bugs and request enhancements
• How to open a pull request
• Code and style conventions (optional)
• Code review process (optional)

CHANGELOG.md

The /CHANGELOG.md file should contain a record of all relevant changes in the project, including new features, bug fixes, and other modifications.

A widely accepted standard for CHANGELOGs is Keep a Changelog, which suggests a specific format and guidelines for organizing and documenting changes, including:

• Added for new features.
• Changed for changes in existing functionality.
• Deprecated for soon-to-be-removed features.
• Removed for now removed features.
• Fixed for any bug fixes.
• Security in case of vulnerabilities.

Some tools can help automate the maintenance of the CHANGELOG and ensure compliance with a standard, such as the aforementioned Keep a Changelog:

• Conventional Changelog: Conventional Changelog is a collection of tools and conventions that automatically generate a CHANGELOG based on Git commit messages. It works well for both monorepo and single-repo projects.

• Lerna: For monorepo projects, Lerna is a management tool that can help manage and publish various parts of the project from a single repository. It can also be used in conjunction with Conventional Changelog to automatically generate CHANGELOGs for each package in the monorepo.

• Semantic Release: Semantic Release is another tool that can automate CHANGELOG generation, as well as package versioning and publishing. It can be used in both single-repo and monorepo projects and follows the SemVer specification.

• Husky: Using Git Hooks through Husky is an effective way to ensure CHANGELOG consistency, as it allows for automatic verification of commit messages against a specific specification, such as the mentioned SemVer, before being accepted into the repository. By ensuring that commit messages follow a specific pattern, a consistent CHANGELOG can be generated.

Conventional Changelog focuses on generating and maintaining CHANGELOG files based on commit messages, while Semantic Release focuses on automating package versioning and publication, with CHANGELOG generation as an additional feature. Both tools follow specific conventions and can be used together to automate various aspects of software project management.

Implementation

To implement the proposed documentation template, we should follow the steps below for each project in the Admin team (including templates like admin-ui-example and the future raccoon template):

• Create a /docs folder in the repository if it doesn't exist yet.
• Create and fill in the /README.md file based on the proposed structure and relevant project information.
• Add the /CONTRIBUTING.md file or include a "How to Contribute" section in the README.mdfile with contribution guidelines.
• Create and maintain the /CHANGELOG.md file, following the Keep a Changelog standard and utilizing the mentioned tools for automation and consistency.
• Add other project-specific documentation files (such as ARCHITECTURE.md, OBSERVABILITY.md, etc.) as needed, including links to them in the` README.md file.
• Insert comments and jsDocs in the code when necessary to explain complex or non-obvious parts of the code.
• Utilize the project's Wiki (optional) to include additional or specific information that doesn't fit into other documentation files, including links to them in the README.md file.
• Configure and use the suggested tools (Conventional Changelog, Lerna, Semantic Release, and Husky) to help maintain consistency and automation in the CHANGELOG maintenance and project versioning, unless the project already follows this pattern through releasy.
• Last but not least, periodically review and update the documentation to ensure it remains up-to-date, reflecting the changes and evolution of the project.

[davicostalf]

Documentation File Structure
All documentation within the root folder:
[...]
/docs/.md (e.g., ARCHITECTURE.md, OBSERVABILITY.md, LOCALIZATION.md, CACHING.md, INTEGRATION_TESTS.md, tutorials, guides, etc.)
Comments/jsDocs in the code when necessary
Wiki (optional)

Considering we also have the documentation website, I would detail what type of documentation should be in the repository and what should be in the website. I also don't think we should use the wiki feature in GitHub, as we already have the website. Maybe documentation for maintenance should be in the repository and usage/contribution should be in the website. The only exception I think should be the README, since it's already common practice for it to include the information that you listed.

[rafaelnader]

What kind of documentation are we producing or willing to?

I would split this discussion into specific ones: Contributing, Changelog, Doc.