ADR-0004: Which framework could be more useful for documentation purposes?
| Status: | ACCEPTED (SUPERSEDES ADR-0001) |
| Date: | 2020-09-29 |
| Author(s): | Daniel Patanin daniel.patanin@iteratec.com |
Context
Since the last major update of our GatsbyJS based website, the original requirements for our ideal webpage have changed. Originally we needed a website, which could present our project briefly and hold the documentation, dynamically build from our main repository. The first aspect has changed quite severe since we aim for an actual marketing oriented homepage now. The second goal stays the same, but changed contextually. We no longer just want to host the documentation, but furthermore want to stay on modern documentation standards and since our team does not want to invest too much time into the documentation site’s development and maintenance, we are looking for a component library or whole framework specialized on documentation.
Decision
We did not evaluate many different frameworks. The journey was quite short in fact. The first documentation oriented framework we looked at was Docusaurus. As I progressed into trying out to build a basic Docusaurus site and copied all documentation files into it, the website actually looked nice and quite finished already, after only a few hours of tinkering. It is that easy and simple to understand, especially with it’s own good documentation. After reviewing this very basic website, we decided to advance this and already try to retrieve the documentation remotely from our main repository. At this point the decision was pretty clear already: If there is no major drawback coming up, Docusaurus is our new framework of choice. And there was no drawback major enough to revoke this decision (yet). Everything we programmatically wanted to achieve, we could do so by basic scripting and we never really have to think about components like the sidebar, navbar etc. since this is all done completely automatically by Docusaurus itself.
Consequences
As simple and easy it sounds, so it is, meaning that since the build is automated to a very big degree, we are forced to follow Docusaurus' exact guidelines and mechanics. For now they are almost identical to what we require. And of course we can build custom components and custom pages, but the documentation and blog part of the site are very strict. Since we want to use this website mainly (ideally only) for documentation purposes, we need a separate marketing page. As far as maintenance goes, we mostly need to maintain our custom build scripts. Everything else is very much automated.