matomo-org / matomo-org/developer-documentation

Remove some metadata / yaml from docs

Open
#73 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Documentation enhancement
Dominant language
PHP
Stars
58
Forks
88
Avg merge
6d 3h
Merged PRs (30d)
13

Description

I was wondering if we actually need the metadata defined in the beginning of `docs/*.md` files?

```
category: Develop
previous: tests-ui
next: tests-travis
subGuides:
- plugin-settings
- piwiks-ini-configuration
```

In theory this information is already present in the category classes, isn't it? For example here: https://github.com/piwik/developer-documentation/blob/master/app/helpers/Content/Category/DevelopCategory.php

Depending on the path or filename of the markdown file we know the `category`. Currently, when moving a page to another category I do have to update the PHP category classes and update the related markdown file.

Also `previous` and `next` could be maybe automatically generated for all pages and not needed to be defined in the markdown files since we have that information already in the category class? Meaning we can find out whether there is a previous or next sibling.

With `subGuides` I was confused why it is sometimes defined in the markdown file and sometimes in a category class. I think we could just remove it and for simplicity always define it in the category class so one can immediately see the whole structure there and change things in one place.

Of course we'd have to create all category classes to know all this information but that should be fast. Especially since we cache pages.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Compare the metadata in docs/*.md with the category definitions in app/helpers/Content/Category/DevelopCategory.php and the other category classes. Determine whether category, previous/next, and subGuides can be represented consistently in the category classes; done means the duplicated front matter is removed without losing the documented structure or navigation.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
documentation
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.