karenmajewicz
commented
1 year ago Addressing this issue and #https://github.com/OpenGeoMetadata/opengeometadata.github.io/issues/72:
I made a fork of the OGM Website and applied the mkdocs.org framework. I then reorganized the information by trying to follow the principles of Diataxis. It's pretty fun to work on - I got a bit carried away and ended up with this: https://karenmajewicz.github.io/opengeometadata.github.io/
Overall, I felt like this structure made it easier to bring useful information into a more prominent view, such as the crosswalks. I also thought about info that had been reported as hard to find (ex. GBL 1.0 or the References URIs) and made them separate pages under the nav.
Some things to note:
- I started off using the readthedocs theme for MkDocs, but ended up using the Material theme instead as is so much more versatile and is actively developed.
- For the tables, we are able keep the information natively as CSV files. There is a plugin that reads them as Markdown. This makes it much easier to update tables.
- There is also a plugin to sort the tables (click on an icon that appears when you scroll over a header)
- The navigation style is configurable - it can be all on one side, split into two sides, and/or have a top menu. Also, we don't need to define the TOC for each page - it can be automatic based on headers
- The internal links compiling is a bit different, so I had to tack on ".md" to them. I think I caught all (?) of them though. When you build or deploy the site, it warns you about broken links. (But, there might be differences as well if a custom domain is applied.)
The metadata team did some initial reorganizing of the website (see https://github.com/OpenGeoMetadata/opengeometadata.github.io/issues/36) but feedback suggests we could improve the structure further, particularly to make the legacy schema more findable.
Suggestion to use https://diataxis.fr/ as a guideline for restructuring.