In any organization, trade jargon and acronyms are little bit of a thorn for new comers.
To help with onboading experience of new contributors for user documentation, I would like to create a Fedora Docs glossary.
Objective
Create a consolidated Docs glossary of working groups/SIGs that maintain docs pages (Docs team, Workstation, Server, CoreOS, Cloud, IoT, Silverblue, Kinoite, EPEL and more)
Publish it in contributor pages
Use it for onboarding new people, who show interest in maintaining user documentation
Please let me know if this is a good idea by clicking âthumbs-upâ emoji.
I can think of a couple of those terms and definitions that might help onboarding.
Upstream documentation
Local preview
Git forge
Technical review
Repositories
Clone vs fork
Docs builds
Deploy docs
Merge conflicts
Docs team will also âshow and tellâ these definitions of Docs glossary during monthly writing workshop, which started in September 2023.
What about a universal and automatically generated system of tool tips for short definitions that are added to doc pages? These could be delivered as tool tips when the mouse hovers over whatever confusing term has been defined as needing clarification. It could be indicated in a way like/similar to linking text.
Once created and intergated with the fedora doc system it can be implemented across many systems. The way Wikimedia has implemented link previews as tool tips on link texts is a good example.
Any system that assumes people will read even more documentation is a bit ambitious and may not be as useful as could be hoped.
Well, the âtool tipâ technique is quite simple to implement, the âautomatically generatedâ feature less so. We would need to have a post processor for the Antora generated pages or something like that. Nevertheless, before that, we would need a list of probable miss understandable terms and its explanations. So, such a page would be a good starting point anyway.