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.
- 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
- 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.
Totally open to ideas on UI element. Thanks for your suggestions on CSS Tooltip attribute.
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.
Docs team will introduce ‘Jargon buster’ on the Writing workshop on 16 November 08:00-08:30 UTC.