Glossary: Updated J terms #152
Conversation
|
Hi @s-makin , I would love your feedback! |
There was a problem hiding this comment.
Thanks @Ibom99 for your work in adding these terms. I really like the definitions you created, and you've also highlighted another (separate) issue that I hadn't noticed before around journald. I've left a few suggestions inline, but overall it's looking really good :)
reference/glossary.rst
Outdated
| *Work in Progress* | ||
| Jitter is the variation in delay or latency between when data packets are sent and when they are received over a network, causing irregular arrival times at the destination. This variation is often caused by network congestion, packet loss, poor hardware performance or differences in the path packets take. | ||
|
|
||
| Related topic(s): :term:`Chrony`. |
There was a problem hiding this comment.
This seems like a broader topic than just chrony - I think we could change the related topic to just networking in general :)
There was a problem hiding this comment.
Okay that works, I'll make modifications, i.e: Related topic(s): Networking
reference/glossary.rst
Outdated
|
|
||
| journald | ||
| *Work in Progress* | ||
| Journald is a logging driver that sends container logs to the systemd journal. |
There was a problem hiding this comment.
I think we can expand on this definition a little, as it implies that it's a Docker-related thing but it's a bit broader than that. journald is the part of systemd that handles logging. For containerized systems like Docker, it can act as a logging driver for containers.
I think it would make sense here to link to the manpage for journald.conf as well.
There was a problem hiding this comment.
How about this reflecting all suggestions on journald:
Journald, also known as systemd-journald, is a logging service developed by the systemd project as part of the systemd suite. It collects and stores log messages from various sources, including systemd services, kernel messages, system logs, and application logs. Journald stores logs in a binary format offering advantages, such as storage efficiency, searchability, and most especially structured logging. In containerized systems like Docker, it functions as a logging driver for containers.
See manpage for journal.conf for more information.
See the Docker journald documentation for details on using journald as a logging driver.
Related topic(s): Logging & Docker.
There was a problem hiding this comment.
That sounds like a great re-write :) once we have a page about journald we may decide to put some of these details there instead and trim this description down accordingly. But since we don't have anything yet I think providing the extra detail here makes a lot of sense and will be helpful to the reader.
There was a problem hiding this comment.
The only suggestion I have to add to your re-write is to separate "logging" and "Docker" with either a comma or "and". Sometimes the ampersand symbol can cause problems, so we try to avoid using it outside of code blocks.
There was a problem hiding this comment.
Noted! I would push the changes right away
reference/glossary.rst
Outdated
| *Work in Progress* | ||
| Journald is a logging driver that sends container logs to the systemd journal. | ||
|
|
||
| See `journald <https://docs.docker.com/engine/logging/drivers/journald/>`_ for more details. |
There was a problem hiding this comment.
I'd suggest expanding this bit of text to provide a bit more context for the reader on where the link will take them. Something like:
See the Docker journald documentation for details on using journald as a logging driver.
Or something like that. What do you think?
There was a problem hiding this comment.
This would be helpful for sure
reference/glossary.rst
Outdated
|
|
||
| See `journald <https://docs.docker.com/engine/logging/drivers/journald/>`_ for more details. | ||
|
|
||
| Related topic(s): :term:`Docker`. |
There was a problem hiding this comment.
I think we can put "logging" here as a topic as well as Docker :)
There was a problem hiding this comment.
(which has made me realise that we only have journald content under Docker right now, which we'll need to queue up as follow-up improvements!)
reference/glossary.rst
Outdated
| JSON | ||
| *Work in Progress* | ||
| **JavaScript Object Notation**: | ||
| This is a text format that is completely language independent but uses conventions that are familiar with programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others. JSON is a syntax for serializing objects, arrays, numbers, strings, booleans and null, and is a subset of the JavaScript syntax. Due to its simplicity, it is an ideal lightweight data interchange language. |
There was a problem hiding this comment.
I really like this description, but the middle sentence (the "JSON is a syntax for serializing...") feels like it might need additional context for some readers, and I think the description overall feels more complete without it. Could we remove it?
There was a problem hiding this comment.
Thank you! Yes, we can keep it concise, with the suggestion it would look like:
This is a text format that is completely language independent but uses conventions that are familiar with programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others. Due to its simplicity, it is an ideal lightweight data interchange language.
reference/glossary.rst
Outdated
|
|
||
| See `JSON <https://www.json.org/json-en.html/>`_ for more details. | ||
|
|
||
| Related topic(s): Ubuntu Server & :term:`Docker`. |
There was a problem hiding this comment.
We probably don't need related topics for this one - it's a broad enough term with wide enough applications that we couldn't possibly list them all, which means we can just list none :)
My pleasure! I will work on your suggestions shortly |
|
Hi @s-makin please review the modifications |
There was a problem hiding this comment.
Thanks again @Ibom99 for your work contributing to the Ubuntu Server glossary :) the descriptions you wrote are really clear and concise, and this will be a really helpful addition for our users. Thanks for helping to make the Server docs better!
My pleasure! I look forward to working on more! |
You'd be most welcome to! There's always plenty to do, so if you have specific types of issues you're looking for I can bring those forward :) |
Description
This pull request updates the "J" terms in the glossary.
Related Issue