Add content for Paragraphs

style-guide/hdocbook.json

@@ -178,10 +178,6 @@
                 "text": "Dates and times (EL: WIP)",
                 "link": "style-guide/dates-and-times"
               },
-              {
-                "text": "Figures (EL: WIP)",
-                "link": "style-guide/figures"
-              },
               {
                 "text": "Footnotes (EL: C)",
                 "link": "style-guide/footnotes"
@@ -198,6 +194,10 @@
                 "text": "Notes and notices (EL: C)",
                 "link": "style-guide/notes-and-notices"
               },
+              {
+                "text": "Paragraphs (EL: C)",
+                "link": "style-guide/paragraphs"
+              },
               {
                 "text": "Procedures (EL: C)",
                 "link": "style-guide/procedures"

style-guide/paragraphs.md

@@ -0,0 +1,77 @@
+# Paragraph construction
+
+<code>ELMER: Complete</code>
+
+Effective paragraph construction is essential for clarity and readability in technical documentation. The following guidelines outline best practices for structuring paragraphs to ensure concise and comprehensible communication:
+
+- Begin each paragraph with a topic sentence clearly stating the main idea, helping readers grasp the key message quickly.
+
+  **Example**<br>
+  **Cloud computing security**
+
+  Cloud computing security is critical for protecting data in the digital age. It involves various strategies to safeguard information stored online from unauthorized access and cyber threats.
+
+- Confine each paragraph to a single main idea or topic to maintain focus and ease of understanding.
+
+  **Example**<br>
+  One key aspect of cloud computing security is encryption. Encryption ensures that data is transformed into a secure format, making it unreadable to unauthorized users.
+
+- Employ transitional words or phrases to connect ideas within and between paragraphs smoothly, enhancing the flow of information.
+
+  **Example**<br>
+  Furthermore, access control mechanisms are essential. They restrict user access to sensitive data, ensuring only authorized personnel can view or modify it.
+
+- Keep paragraphs concise and include only information pertinent to the paragraph's main idea.
+
+  **Example**<br>
+  Regular security audits are also crucial. They help identify potential vulnerabilities in the cloud infrastructure.
+
+- Arrange sentences logically, straightforwardly constructing your argument or description for the reader to follow.
+
+  **Example**<br>
+  Initially, a risk assessment is conducted. Following this, appropriate security measures are implemented. Finally, ongoing monitoring ensures the continued effectiveness of these measures.
+
+- Avoid extending sentence length merely to reduce the number of sentences in a paragraph. Instead, opt for shorter sentences and paragraphs.
+
+- Use a combination of short and long paragraphs to retain the reader's interest and attention, avoiding overly long paragraphs that might overwhelm the reader.
+
+  **Examples**
+    - Short paragraph example
+
+      Firewalls are a basic defense. They monitor and control incoming and outgoing network traffic based on predetermined security rules.
+
+    - Long paragraph example
+
+      In addition to firewalls, multi-factor authentication adds another layer of security. It requires users to provide two or more verification factors to gain access to cloud resources. This method significantly reduces the risk of unauthorized access, combining something the user knows (like a password) with something the user has (such as a smartphone app).
+
+- Where necessary, link back to previous ideas or forward to upcoming concepts to provide context and continuity.
+
+  **Example**<br>
+  As previously mentioned, encryption plays a vital role. Building on this, data backup strategies further enhance security by ensuring that, even in the event of data loss or corruption, information can be recovered quickly and effectively.
+
+- Strive for clear and simple language to make your text accessible to a broad audience, including those who might not be native English speakers.
+
+  **Example (incorrect) ❌**<br>
+  Cloud security frameworks necessitate user interaction with multifaceted authentication mechanisms and the configuration of intricate network protocols, demanding advanced technical acumen from end-users.
+
+  **Example (correct) ✅**<br>
+  Cloud security solutions should be user-friendly, allowing users of varying technical abilities to manage their data security effectively.
+
+- Unless crucial, avoid industry-specific jargon and overly complex language that might confuse the reader.
+
+  **Example (original technical language) ❌**<br>
+  Implement stringent SSL/TLS protocols to encrypt client-server communication channels and utilize OAuth 2.0 for secure API authorization.
+
+  **Example (revised for clarity) ✅**<br>
+  Ensure secure communication between users' devices and servers by using advanced encryption methods. Also, use reliable techniques for verifying who can access the system's data and services.
+
+- Conclude paragraphs with a sentence summarizing the main point or transitioning to the next idea, if applicable.
+
+  **Example**<br>
+  Thus, maintaining robust cloud computing security is indispensable for protecting sensitive data in our increasingly online world.
+
+## Paragraph formatting
+
+Align text to the left to enhance readability. Avoid centering, fully justifying, or aligning text to the right.
+
+Refrain from inserting forced line breaks within sentences and paragraphs. Such breaks may not display correctly in resized windows, on different devices, or when text is enlarged.