also add a glossary and begin to use it in the getting-started page
- rDDOC Development documentation
Automatic diff as part of commit; lint not applicable.
Automatic diff as part of commit; unit tests not applicable.
What do the pipe in |swh| mean?
Regarding docs/images/general-architecture.svg: I really like it. Could you add the names of involved technologies (eg. in a box with logo->name matching) so they are easier to search later on?
Regarding mermaid graphs: The text is too small to read without zooming in. Increasing the font size should fix that without breaking the layout.
|8 ↗||(On Diff #2106)|
Missing a closing parenthesis.
|40 ↗||(On Diff #2106)|
and inserts nodes and edges in the graph.
|65 ↗||(On Diff #2106)|
|73 ↗||(On Diff #2106)|
maybe explain the difference between a SHA1 and “git-like” SHA1 in that glossary as well?
Looks like the substitutions file is missing?
- replace mermaid with plantuml
- use sphinxcontrib.images
- better glossary
Regarding the glossary, we also had https://wiki.softwareheritage.org/wiki/Glossary ; once this is pushed the wiki glossary should be deprecated/deleted in favor of the docs.s.o one. In the meanwhile there might be entries there that are missing here (I haven't checked, but wanted to mention potentially useful previous work :-))
I've seen this. Ok to deprecate it ASA this diff is published and the doc is online.
In fact, there are other place(s) where we can find kind of partial glossaries, especially https://docs.softwareheritage.org/devel/swh-model/data-model.html#software-artifacts . Not sure how to deal with this later one however. It makes sense to keep these definitions explicitly in this document, IMHO.
I think we can walk the fine line between a glossary (short definition, for mnemonic use) v. definition (long definition, with all the details). The Data Model can very well be the source for the latter; the glossary for the former. And for each of the relevant entries the glossary can link to the Data Model under a "for more information see [...]" notice.