Skip to main content

How to Have a Well-Documented Project?

· 2 min read
David Puziol Prata
David Puziol Prata
DevOps at @ Encora

Hello readers,

Today we're going to talk a bit about the creation of this site and how it was built using

docusaurus

It simplifies the process of building static sites for technical documentation, making it easier for developers and project teams to manage and present documentation online.

Some key features of Docusaurus include:

Standard Documentation Structure​

Docusaurus provides a predefined structure for organizing documentation, including support for multiple languages, categories, and versioning.

Written in Markdown with React Integration​

Documentation is written in Markdown, a lightweight and easy-to-learn markup language. This makes formatting and writing easier, allowing developers to focus on content, while also allowing the incorporation of React components, providing flexibility and interactivity when needed.

Docusaurus includes built-in search functionality to help users quickly find the information they need.

Customizable Theme​

While Docusaurus comes with a clean and responsive default theme, users can customize the appearance of the documentation site as needed.

Version Control Integration​

It's possible to organize documentation for different versions of a project, making it easy to reference documentation corresponding to a specific version of the software.

To start the project, install Node.js in the latest version.

sudo apt-get install nvm -y
nvm install node

node --version
v21.5.0

npx create-docusaurus@latest my-site classic

cd my-site

# Building the project
npm run build # will generate the static code
npm run serve

In the browser localhost:3000

Alt text

The my-site folder has this structure

.
├── babel.config.js
├── blog
├── build
├── docs # Example documentation is here
├── docusaurus.config.js
├── node_modules
├── package.json
├── package-lock.json
├── README.md
├── sidebars.js
├── src
└── static

Of course, you can run all these commands directly in your project repository and it will create the my-site folder with the structure above.

Use the template in the docs folder and create the project documentation.

Whenever you want to see the documentation, run npm run serve

You can also set up a delivery pipeline to host the site somewhere and always have the most up-to-date documentation for your team and clients!