Related documents (#2584)

* Mock up for additions to Documentation site
* Add top-level menu "More Insights"
* sub-categories: announcements, blogs, links
* Add `active_voice.md` and `open_source.md` to blogs along with `index.md`

* Final fixes for top level category
* updated `.pages` files as necessary
* updated `index.md` files with content
* rephrased some sentences in the blog posts

docs/.pages

@@ -7,4 +7,4 @@ nav:
     - Gemstones: gemstones
     - Desktop: desktop
     - Release Notes: release_notes
-    - Rocky Linux: https://rockylinux.org
+    - Rocky Insights: rocky_insights 

docs/rocky_insights/announcements/.pages

@@ -0,0 +1,5 @@
+---
+nav:
+    - ... | index*.md
+    - RSOD: rsod
+    - ...

docs/rocky_insights/announcements/index.md

@@ -0,0 +1,7 @@
+---
+title: Introduction 
+author: Steven Spencer
+contributors:
+---
+
+This is a new area meant to deal with team and project announcements. This will include things such as "Rocky Summer of Docs" (RSOD) guidelines, and documentation team goals. You will find the archived RSOD projects here as well.

docs/rocky_insights/blogs/active_voice.md

@@ -0,0 +1,60 @@
+---
+author: Steven Spencer
+contributors:
+---
+
+# Active voice: The way to simple, clear, communication
+
+## Active verses passive voice
+
+There is a huge debate these days on the use of active voice in documentation. There should not be. The reason is that using active voice helps create documentation that is direct and clear. I read a social media post recently where they were questioning this reality. The gist of the conversation was: *'Passive voice does not seem that bad in documentation, should I care?'* I can assure you that it **does** matter, and you **should** care. Passive voice is often ambiguous and unclear. Passive voice can lead to confusion in technical writing, particularly where your audience varies and where translations occur. Our goal with Rocky Linux documentation is to have great documentation, and great documentation does not include the use of passive voice. Examine this from our "Style Guide":
+
+> Say what you mean in as few words as possible.
+
+Active voice forces this. Here is an example of a passive voice instruction:
+
+For our web platform, Apache must be installed using this command: `sudo dnf install httpd`
+
+While here is the active voice equal:
+
+For your web platform, install Apache with this command: `sudo dnf install httpd`
+
+A couple of things are notable in this example. The passive voice phrase has 11 words while the active voice has 9. The active voice phrase directs the user to "install" Apache, rather than telling them it "must be installed." In both examples, though, the instruction, the most important element, hides in the body of the sentence. While 9 words is an improvement, we can do more. If you remember the "Say what you mean in as few words as possible" rule, then consider this:
+
+Install Apache with: `sudo dnf install httpd`
+
+Again, we use active voice, but now just 3 words instead of 9 (or 11). In addition, our instruction could not be more clear. It is simple and direct. This has repercussions for translation, and document structure. Translating 3 words takes less effort for our translators. The 3 word instruction is clear to your readers. It is a win all around.
+
+When striving for clear instructions, combining simplification with active voice helps in achieving your goal.
+
+## Identifying passive voice
+
+When I first started writing documentation for Rocky Linux back in 2021, I started with a cache of documents I wrote when still working as a network administrator. My documents were full of passive voice phrasing, and at the time, I could not identify them easily. It was not until late 2023 that the editor that I began to use for both creating and editing documents ([Neovim based](https://neovim.io/) editor with [Vale](https://vale.sh/)) started highlighting passive voice phrases. It was difficult to train my eye to "see" the passive voice phrases at a glance. It still is not always easy to see. Here are things to watch for to help identify passive voice:
+
+* Instructions starting with or including 'we' or 'our'
+
+    These almost always lead to phrasing that is first, indirect, and often includes passive voice. Use 'you' or 'your' in your writing of instructions.
+
+* Watch for verbs such as: 'was', 'were', 'are', 'been', 'be', and so on, followed by a past participle phrase usually (but not always) ending in "ed." Examples:
+
+    * "was created"
+    * "were backed up"
+    * "are manipulated"
+    * "been restored"
+    * "be installed"
+    * "is hidden"
+
+    Each of these is an example of passive voice.
+
+* Watch for sentences where the instruction is **not** the first, most important, element (the subject).
+
+You can train your eye to see these when proofreading, but if you stick to a goal of simplifying your instructions, you will find that elimination of passive voice happens without much effort. It is still **very** helpful to use an editor that supports Vale integration.
+
+## Conclusion
+
+Using active voice in your technical writing helps to ensure simple, clear, instructions. In addition, further simplification of your writing enhances readability, understandability, and helps ease translation efforts. Remember: "Say what you mean in as few words as possible."
+
+## More reading
+
+* Tech Whirl - [Avoiding Passive Voice](https://techwhirl.com/avoiding-passive-voice/)
+* Google Developers - [Active voice vs. passive voice](https://developers.google.com/tech-writing/one/active-voice)

docs/rocky_insights/blogs/index.md

@@ -0,0 +1,35 @@
+---
+title: Introduction
+author: Steven Spencer
+contributors:
+---
+
+## Why this section?
+
+Towards the end of 2024, it became evident that not every document in the Rocky Linux documentation cache will be an how-to guide. We needed a spot for longer, more in-depth explanations. Enter this blog.
+
+## Who can write here?
+
+Anyone who has GitHub credentials can submit a suggested article here. Review the documents in the [Contribute section](https://docs.rockylinux.org/guides/contribute/) to get started.
+
+!!! note
+
+    If you do not have GitHub credentials and still want to write something for this section, contact us in the Mattermost channel link at the bottom of this page.
+
+You should ensure your document fits the requirements for this section. For instance:
+
+* Does it fit here? For instance, is this a fit for this blog-style format? Is it information worth sharing?
+* Does it expand on a subject important to documentarians?
+* Will the submission enhance the overall quality of all of the Rocky Linux documentation?
+
+## What kind of information?
+
+The first two documents here should give you an idea of what fits. Throughout 2024, we made a concerted effort to eliminate or drastically reduce passive voice in the how-to documents. The document [Active voice: The way to simple, clear, communication](active_voice.md) describes the importance of active voice in the tone of the documentation, the ease of reading and understanding, and the simplification in translating to other languages.  The document [Open source: Why it is never hyphenated](open_source.md) discusses the big debate over this subject and the reasoning behind our decision not to hyphenate. Get the idea? These are informative documents that do not include how-to information, except perhaps as examples.
+
+## Growth of this blog?
+
+The expectation is that this set of documents will grow more slowly than the how-to documents. That is alright. It is the quality and fit of the documents here that is most important.
+
+## Feedback
+
+As with the documentation project as a whole, you can give feedback in our [Documentation Mattermost channel](https://chat.rockylinux.org/rocky-linux/channels/documentation).

docs/rocky_insights/blogs/open_source.md

@@ -0,0 +1,34 @@
+---
+author: Steven Spencer
+contributors: 
+---
+
+# Open source: Why it is never hyphenated
+
+## Open source or open-source, the debate is over
+
+There was a time when using the hyphenated version of open source was acceptable if used as an adjective before a noun, but no more. The reason? Open source has become part of the lexicon as a compound noun. Using it as an adjective is no-longer acceptable practice. Lexicalization is the process where a word or phrase becomes an established part of a language, in this case our technical language. Here is how the Open Source Initiative describes it:
+
+> The word open in “open source” does not have the meaning “open” as one would find in the dictionary. Instead, “open source” also entails user freedoms, inasmuch as users of the software for any purpose do not have to negotiate with the rights owners to enjoy (use/improve/share/monetise) the software. That is, it is not only about transparency.
+
+You will still find sources out on the Internet telling you that you should hyphenate open source when using it as an adjective in front of a noun. The reality is that open source *is* a compound noun, so it should never be an adjective. You get the picture.
+
+## Examples of other compound nouns
+
+Other examples of compound nouns that became part of the lexicon are:
+
+* high school
+* green card
+* yellow journalism
+
+These are all compound nouns. It is pretty easy to see why that is the case. Their meaning as separate words is different from what they mean together. *Yellow* and *journalism* mean different things separately. *Yellow* is a color between green and orange in the spectrum. *Journalism* is the activity or responsibility of writing for a magazine, news, or web resource.  **But** *yellow journalism* is a type of journalism that uses sensationalism and exaggeration. It is a noun.
+
+These are not part of our technical vocabulary, but it is easy to see how they relate to open source, which is.
+
+## Conclusions
+
+As stated earlier, you will find sources to support the use of a hyphen in open source (if the adjective rules apply), so it comes down to a project making a decision and sticking to it. As far as the Rocky Linux documentation project goes, we believe that you should never use "open source" as an adjective. We choose to **only** use it as a compound noun following the example of the Open Source Initiative. By doing so, we remove the debate and relieve the pressure on our documentarians when editing or creating, eliminating questions. The goal is to keep things simple and clear.
+
+## Other reading
+
+* The Open Source Initiative - [Is "Open Source" ever hyphenated?](https://opensource.org/blog/is-open-source-ever-hyphenated)

docs/rocky_insights/links/index.md

@@ -0,0 +1,12 @@
+---
+title: Rocky Links
+author: Steven Spencer
+contributors:
+---
+
+* Rocky Linux [main website](https://rockylinux.org)
+* Docs Team [Mattermost](https://chat.rockylinux.org/rocky-linux/channels/documentation)
+* [Forums](https://forums.rockylinux.org)
+* [Wiki](https://wiki.rockylinux.org)
+* [Code of Conduct](https://rockylinux.org/about/coc)
+* [Account Services](https://accounts.rockylinux.org)