Skip to main content

Reorganizing our docs

· 4 min read
Guille
Guille
Docs Maintainer

We released a mayor reorganization of our repository, so we can improve docs for everyone... including us

Organic growth​

Our documentation is the result of multiple people collaborating across the span of four very active years, and it has seen a lot of changes: 2942 commits and counting.

In the beginning, our docs only needed to explain how to create smart contracts, and how to interact with them through a frontend. Fast forward to today, and we have more than 200 pages of documentation, covering topics such as chain abstraction, on-chain components, data infrastructure, and primitives such as NFT, FT.

The best thing is that new features are released every single month. However, all progress comes at a cost, and as our ecosystem grew, so did the disorganization of our documentation.

Let's briefly explain how docusaurus (the framework we use in our docs) works so you can understand the problem.

In docusaurus, all the pages are written as simple markdown files. These files go inside the ./docs folder, and can be organized in folders. Each file has a unique ID on its header that identifies it (e.g. id: what-is), and this ID, alongside its folder path, is used to generate the URL.

For example, the document docs/build/smart-contracts/what-is.md has the id: what-is, so it ends being served in the URL https://docs.near.org/build/smart-contracts/what-is.

The problem​

About a year ago, we noticed that our organic growth had left us with a very inconsistent URL structure. Basically, we had a lot of folders, and the files related to the same topic (e.g. NEAR components) would be all over the place.

For example, you would be in the "Build" section reading about "What is a NEAR Component?" and the URL was /bos/tutorial/quickstart. The next page was "Setup an Environment" located at /bos/dev/intro, followed by "Anatomy of a Component -> State" at /bos/api/state. Talk about consistency!

Of course, we did not do this on purpose, it is just how things evolved. You might even notice that we are now talking about "NEAR Components" but the URL talks about "BOS". This is because when we started, "BOS" (Blockchain Operating System) felt like a good name, but community feedback made us know that, indeed, it was not.

The migration​

We re-organized more than 200 files to a new structure that is more consistent. This makes it easier for users to remember the URLs, improves our SEO, and makes it easier for contributors to find where to add new content. No more need to search across multiple folders trying to find the right file!

In the process, we updated all internal links, aided by our link-checker script to make sure we left no broken links. We also added URL redirects in our server, so all users coming from an external site are redirected to the correct URLs.

Besides checking broken links, we took the time to make sure all the translations were correctly migrated. The system Docusaurus uses (called Crowdin) is not very good at detecting changes in a file, so migrating all the translations was a huge effort in itself.

We could write a blog post just about migrating translations in docusaurus + crowdin... but we will spare you the pain.

Missing URL

If you come across a URL that is not working, please let us know by using the Feedback button on the right side of the page, or by opening an issue in our repository

What's next​

Now that most of our documentation is in a better shape, we can focus on improving the content itself. We have a lot of ideas on how to make the docs more interactive, and we are excited to start working on them.

Stay tuned for more updates, and remember that if you have any feedback or ideas, you can always reach out to us. We are always happy to hear from you!

See you in the next post! 🚀