📝✨ Documentation Platform Evaluation

[cwaring]

TLDR: we will use VuePress to build the new POC IPFS Docs.

---

💫 Overview

After exploring many options for our new documentation platform I've narrowed our focus down to three possible choices to help us achieve our goals and provide a better developer experience for the IPFS team, as well as community contributors.

This is based on the primary aims of:

• Improving the reading/discovery experience of the docs
• Improving SEO/Deeplinks/Permalinks
• Adding Internationalization
• Supporting versioning of docs
• Adding rich search capability
• Improving accessibility
• Improve embedded API documentation

Note: both open and closed source products were evaluated with the goal of selecting an OSS option that is in line with our project providing flexibility to customize as our requirements grow.

📊 Evaluation categories

I have performed deeper testing and prototyping with the top 3 selected platforms to analyze the best fit based around a few primary categories.

• Out of the box features: features included that are relevant to a documentation project.
• Customizability: can we customize the view layer at template level?
• Extensibility: how easy is it to hook into the build process to augment the output?
• Extensions available: how many relevant extensions are already available?
• Developer experience: what is it like to use the framework and customize it?
• Active development: how active is the OSS project?—code committed and issues closed, community replies.

📈 Gradings

Scale: 1 – 10

Docusaurus 1.x (total 25/60)

• Out of the box features: 9
• Customizability: 5
• Extensibility: 2
• Extensions available: 0
• Developer experience: 6
• Active development: 3 (maintenance mode)

Docusaurus 2.x-alpha (total 38/60)

• Out of the box features: 6 (vs 9 for 1.x due to alpha state)
• Customizability: 7
• Extensibility: 8
• Extensions available: 4
• Developer experience: 8
• Active development: 5 (Active but slow and missing two key features: i18n & versioning)

Gatsby 2.x (total 48/60)

• Out of the box features: 5
• Customizability: 10
• Extensibility: 9
• Extensions available: 8 (most not documentation focused)
• Developer experience: 6
• Active Development: 10

VuePress 1.x (total 48/60)

• Out of the box features: 7
• Customizability: 9
• Extensibility: 8
• Extensions available: 8
• Developer Experience: 8
• Active development: 8

💁‍♀️ Summary

Evaluating these options leads to the following conclusion:

Gatsby - best in class for static websites/apps, complex & higher development effort.

Richer platform, with a lower level focus to build full custom serverless applications. Overall high confidence for longevity due to the funding, momentum of React, company setup and development activity, however this would require significantly more bespoke development in order to achieve the documentation experience we desire.

VuePress - minimalistic framework with a stronger focus around documentation by default.

It is possible to build full WebApps using VuePress however the strength is for documentation sites, development is active and available plugins/themes will provide a great baseline experience without substantial customization.

✍️ Proposal

Our priority is to provide the most value to IPFS users with a balanced amount of required development effort due to our small team and broad responsibilities. With this context Vuepress shows the most promise for us deliver this result in a timely way.

Starting in Q4 our team will focus on building out a POC with VuePress, leaning on our prioritized feature list as a roadmap new functionality.

👀 Referenced resources

• Priortized feature list
• Evaluation matrix

closes: #198

[jessicaschilling]

@cwaring Awesome 😎 ... linking to this in the repo readme. Many thanks!

[samajammin]

Hi folks! This is super valuable, thanks for documenting this. I'm considering a similar evaluation for ethereum.org. I just requested access to your evaluation spreadsheet - hope it's ok to open up view access. Thanks again!

[jessicaschilling]

@cwaring -- pinging you per @samajammin's note above. Thanks!

[cwaring]

Hi @samajammin, great to see you here! I've invited you to the spreadsheet - it's more raw than this evaluation but hopefully it will help you get a head start on this process too. I'm more than happy to help and it would be great to share additional learnings as we get deeper into the transition so I'm keen to keep this conversation open :)

[erlend-sh]

I know the decision has been made and it seems good 👍 But since other projects are coming by here to inform their own evaluations, I’d like to add https://github.com/doczjs/docz to the list. It is built on top of Gatsby and very actively developed.

For future evaluations I might also suggest one additional criteria:

• Sustainability: Will this project be around for years? I.e. Is it being developed with support of company sponsorship, business model etc.

[jessicaschilling]

Thanks, @erlend-sh! Sustainability was certainly table stakes in our evaluation — though your comment illustrates we could have been more explicit about that. 😊