The main advantage of my proposal over FEP-cb76: Content Addressed Vocabulary is that it provides a method to tie documentation and specfification together. With FEP-cb76, you need to know the exact definition to understand the url.
Rereading it my writing is probably not clear enough, so I’m doing the main example:
- If you request https://w3id.org/fep with accept type “application/ld+json”, you will be redirected to https://codeberg.org/fediverse/fep/raw/branch/main/namespace/fep.json. This is the version for machines.
- If you request https://w3id.org/fep with accept type “text/html” (as a webbrowser) does, you will be redirected to fep/fep.md at main - fep - Codeberg.org. This if for humans.
This simplifies the task for the developer to understand a new namespace. I think this is called “improve developer experience” in tech evangelist speech.
Case study: lemmy
If I wanted to understand a current lemmy message, what would I naively do:
- See the definition of “lemmy” in the
@context
and click on it: https://join-lemmy.org/ns# - I get a 404. I go to the base url https://join-lemmy.org/
- I have to click on “docs” to get a search
- I type in the term, I’m curious about “remove_data” in the search field
- After searching again with my browser for “remove_data” on the page, I find what I’m looking for
With this FEP, this reduces down to 1 step, which is more developer friendly. This is not to say that the documentation of lemmy is bad. It’s basically the second best after ActivityStreams, I’m aware of. for that.
Also my FEP introduces a naming convention, which prevents bugs such as this.
Workload for editors:
As far as the work load goes, one should probably be able to automate the entire namespace, documentation creation and validation.