Docs categories are useless and should be removed completely #104

New Issue

Closed

opened 2024-02-04 19:13:38 +02:00 by nevfy · 2 comments

nevfy commented

2024-02-04 19:13:38 +02:00

Collaborator

"Categories" is a taxonomy title generated by Hugo which has several problems:

It is hard to translate the taxonomy title without hard-coding it directly into the page. #90
Currently, there are only two categories: How-to guides and Tutorials. Those word have almost the same meaning.
Articles tagged with How-To Guides:
- already have a main header which always starts (and always will) with "How to",
- are grouped in the separate folder literally called How-to guides, which can be observed:
  - from the navigation sidebar on the left,
  - the breadcrumb above the main header of the article.
Categories automatically generate separate pages that list tagged articles, that:
- have a different layout from the rest of the Docs (e.g. have no navigation sidebar)
- need to be restyled separately which is excess manual work
Categories can be a useful navigation tool when one article relates to several different topics. This is an unlikely scenario for a documentation with an aim for simplicity. Strict hierarchy where one article relates to one category only is a simpler (and easier to maintain) structure.

What about just removing them completely? At least until the docs grows so big they would actually help navigating it.

This requires:

removing categories from the metadata of tagged articles
disabling taxonomies in the site configuration

"Categories" is a [taxonomy](https://gohugo.io/content-management/taxonomies/) title generated by Hugo which has several problems: * It is hard to translate the taxonomy title without hard-coding it directly into the page. #90 * Currently, there are only two categories: `How-to guides` and `Tutorials`. Those word have almost the same meaning. * Articles tagged with `How-To Guides`: * already have a main header which always starts (and always will) with "How to", * are grouped in the separate folder literally called `How-to guides`, which can be observed: * from the navigation sidebar on the left, * the breadcrumb above the main header of the article. * Categories automatically generate separate pages that list tagged articles, that: * have a different layout from the rest of the Docs (e.g. have no navigation sidebar) * need to be restyled separately which is excess manual work * Categories can be a useful navigation tool when one article relates to several different topics. This is an unlikely scenario for a documentation with an aim for simplicity. Strict hierarchy where one article relates to one category only is a simpler (and easier to maintain) structure. ----- What about just removing them completely? At least until the docs grows so big they would actually help navigating it. **This requires:** - [ ] removing categories from the metadata of tagged articles - [ ] disabling taxonomies in the site configuration

nevfy commented

2024-02-04 19:14:19 +02:00

Poster

Collaborator

@inex what do you think?

inex commented

2024-02-05 10:03:16 +02:00

Owner

How-to guides and Tutorials are different concepts, as defined in Diátaxis. Following it, we shall add Explanation and Reference categories. But these are more like categories that we need to refer to when we write documentation.

I think we may remove taxonomies for now.

`How-to guides` and `Tutorials` are different concepts, as defined in [Diátaxis](https://diataxis.fr). Following it, we shall add `Explanation` and `Reference` categories. But these are more like categories that we need to refer to when we write documentation. I think we may remove taxonomies for now.