Skip to content

Commit f255e08

Browse files
corryrootcorryroot
authored
(DOCSP-43893): Adds nested component guidelines. (#179)
* (DOCSP-43893): Adds nested component guidelines. * (DOCSP-43893): Incorporated Sarah's feedback. * (DOCSP-43893): Incorporated Sarah's feedback. * (DOCSP-43893): Incorporated Lindsey's feedback.
1 parent bb55fd5 commit f255e08

File tree

6 files changed

+395
-0
lines changed

6 files changed

+395
-0
lines changed

‎source/style-guide.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@ MongoDB external and internal customers.
6161
/style-guide/terminology/index
6262
/style-guide/screenshots/index
6363
/style-guide/error-message-guidelines
64+
/style-guide/nested-components
6465
/style-guide/release-notes-guidelines
6566
/style-guide/information-types/index
6667
/style-guide/seo-guidelines

‎source/style-guide/nested-components.txt

Lines changed: 385 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,385 @@
1+
.. _nested-components:
2+
3+
============================
4+
Nested Components Guidelines
5+
============================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. default-domain:: mongodb
14+
15+
To allow LLMs to consume our content easily, don't nest the following
16+
components:
17+
18+
- Callouts inside callouts
19+
- Callouts inside tables
20+
- Examples inside callouts
21+
22+
Use the following guidance to fix existing published nested components
23+
or replace nested components in your pull requests.
24+
25+
Callouts Inside Callouts
26+
------------------------
27+
28+
Remove the nested callout and make its contents part of the parent
29+
callout, or remove it from callouts altogether. The text may
30+
follow directly after the preceding text, or you may include a line
31+
break if appropriate. If the nested callout is an example, see
32+
:ref:`examples-in-callouts`. If the nested callout is an
33+
Important or Warning callout, see :ref:`important-or-warning`
34+
in the :ref:`examples-in-callouts` section.
35+
36+
**Example:**
37+
38+
.. list-table::
39+
:header-rows: 1
40+
41+
* - Before
42+
- After
43+
44+
* - .. important:: AWS Only
45+
46+
Amazon Web Services (AWS) Virtual Private Cloud (VPC) peering
47+
connections are region-specific. Clusters utilizing an
48+
existing VPC peering connection to an AWS VPC in a given AWS
49+
region lose access to that peering connection if moved to a
50+
different AWS region. The moved cluster may use an existing
51+
peering connection in the new region.
52+
53+
.. seealso::
54+
55+
:atlas:`Set Up a Network Peering Connection
56+
</security-vpc-peering>`.
57+
- .. important:: AWS Only
58+
59+
Amazon Web Services (AWS) Virtual Private Cloud (VPC) peering
60+
connections are region-specific. Clusters utilizing an
61+
existing VPC peering connection to an AWS VPC in a
62+
given AWS region lose access to that peering connection if
63+
moved to a different AWS region. The moved cluster may use
64+
an existing peering connection in the new region. To learn
65+
more, see :atlas:`Set Up a Network Peering Connection
66+
</security-vpc-peering>`.
67+
68+
.. _callouts-in_tables:
69+
70+
Callouts Inside Tables
71+
----------------------
72+
73+
.. _notes:
74+
75+
Notes
76+
~~~~~
77+
78+
Remove the nested note directive and make the note's content plain
79+
text. The note text can follow directly after the preceding text, or
80+
you can include a line break if appropriate.
81+
82+
**Example:**
83+
84+
.. list-table::
85+
:header-rows: 1
86+
87+
* - Before
88+
- After
89+
90+
* - .. list-table::
91+
:widths: 20 20 60
92+
93+
* - id
94+
- string
95+
- Unique identifier of this Agent API Key.
96+
97+
* - key
98+
- string
99+
- Agent API Key.
100+
101+
.. note::
102+
103+
After creating this Agent API Key, subsequent requests
104+
return the last four characters of Agent API Keys.
105+
106+
* - desc
107+
- string
108+
- Label for this Agent API Key. Limited to 1,000 characters.
109+
110+
- .. list-table::
111+
:widths: 20 20 60
112+
113+
* - id
114+
- string
115+
- Unique identifier of this Agent API Key.
116+
117+
* - key
118+
- string
119+
- Agent API Key.
120+
121+
After creating this Agent API Key, subsequent requests
122+
return the last four characters of Agent API Keys.
123+
124+
* - desc
125+
- string
126+
- Label for this Agent API Key. Limited to 1,000 characters.
127+
128+
.. _important-or-warning:
129+
130+
Important or Warning
131+
~~~~~~~~~~~~~~~~~~~~
132+
133+
Assess the content and determine whether it really belongs in an
134+
Important or Warning callout. If it's merely noteworthy, remove the
135+
content from the callout. For guidance, see :ref:`callouts`.
136+
137+
If the content could be a note, follow the instructions for
138+
:ref:`notes`.
139+
140+
If users must notice the Important or Warning information (for
141+
example, when ignoring the information results in data loss or other
142+
serious considerations):
143+
144+
- For important information, remove the nested directive and make its
145+
contents part of the parent callout. Precede the important
146+
information with a line break and add ``IMPORTANT:`` in bold, gold
147+
text. To do this, use the following gold directive:
148+
149+
.. code-block::
150+
151+
:gold:`IMPORTANT:`
152+
153+
- For warning information, remove the nested directive and add the
154+
content to the parent callout. Precede the warning information
155+
with a line break and add ``WARNING:`` in bold, red text. To do
156+
this, use the following red directive:
157+
158+
.. code-block::
159+
160+
:red:`WARNING:`
161+
162+
**Example:**
163+
164+
.. list-table::
165+
:header-rows: 1
166+
167+
* - Before
168+
- After
169+
170+
* - .. list-table::
171+
:widths: 30 40 30
172+
173+
* - Restore from Backup
174+
- The time required to restore your serverless instance.
175+
176+
.. important::
177+
178+
Data transfer as part of the backup and restore
179+
process is charged separately.
180+
181+
- Range from $2.50 to $6.00 per restore hour.
182+
183+
- .. list-table::
184+
:widths: 30 40 30
185+
186+
* - Restore from Backup
187+
- The time required to restore your serverless instance.
188+
189+
:gold:`IMPORTANT:` Data transfer as part of the backup
190+
and restore process is charged separately.
191+
192+
- Range from $2.50 to $6.00 per restore hour.
193+
194+
* - .. list-table::
195+
:widths: 30 70
196+
:header-rows: 1
197+
198+
* - Field
199+
- Action
200+
201+
* - :guilabel:`Project`
202+
- Select a :cloudmgr:`project
203+
</reference/glossary/#std-term-project>` to which you
204+
want to restore the :manual:`snapshot
205+
</reference/glossary/#std-term-snapshot>`.
206+
207+
* - :guilabel:`Cluster to Restore to`
208+
- Select a :manual:`cluster
209+
</reference/glossary/#std-term-cluster>` to which you
210+
want to restore the snapshot.
211+
212+
Cloud Manager *must* manage the target replica set.
213+
214+
.. warning::
215+
216+
Automation removes all existing data from the
217+
cluster. All backup data and snapshots for the
218+
existing cluster are preserved.
219+
220+
- .. list-table::
221+
:widths: 30 70
222+
:header-rows: 1
223+
224+
* - Field
225+
- Action
226+
227+
* - :guilabel:`Project`
228+
- Select a :cloudmgr:`project
229+
</reference/glossary/#std-term-project>` to which you
230+
want to restore the :manual:`snapshot
231+
</reference/glossary/#std-term-snapshot>`.
232+
233+
* - :guilabel:`Cluster to Restore to`
234+
- Select a :manual:`cluster
235+
</reference/glossary/#std-term-cluster>` to which you
236+
want to restore the snapshot.
237+
238+
Cloud Manager *must* manage the target replica set.
239+
240+
:red:`WARNING:` Automation removes all existing data from
241+
the cluster. It preserves all backup data and snapshots
242+
for the existing cluster.
243+
244+
.. _examples-in-callouts:
245+
246+
Examples Inside Callouts
247+
------------------------
248+
249+
Remove the nested example and do one of the following steps:
250+
251+
- If the example is a statement with full sentences, add the contents
252+
to the parent callout, preceding the example with a line break and
253+
the text, "For example,".
254+
255+
- If the example is a value in a code block, introduce the code block
256+
with "For example:". If more context follows the example, add "In the
257+
previous example," to the context.
258+
259+
**Example:**
260+
261+
.. list-table::
262+
:header-rows: 1
263+
264+
* - Before
265+
- After
266+
267+
* - .. important::
268+
269+
There must be enough disk space to accommodate all of the
270+
source oplog entries that occur during the initial
271+
``mongomirror`` sync.
272+
273+
.. example::
274+
275+
If the source oplog is 10 GB and covers 24 hours of
276+
changes, and ``mongomirror``'s sync is estimated to
277+
take 48 hours, there must be at least 20 GB of free disk
278+
space in the specified directory.
279+
- .. important::
280+
281+
There must be enough disk space to accommodate all of the
282+
source oplog entries that occur during the initial
283+
``mongomirror`` sync.
284+
285+
For example, if the source oplog is 10 GB and covers 24 hours
286+
of changes, and ``mongomirror``'s sync is estimated to
287+
take 48 hours, there must be at least 20 GB of free disk
288+
space in the specified directory.
289+
290+
Examples Inside Tables
291+
----------------------
292+
293+
Remove the nested example and do one of the following steps:
294+
295+
- If the example is in a statement with full sentences, add its
296+
contents in plain text, preceding the example with a line break and
297+
the text, "For example,".
298+
299+
- If the example is a value in a code block, introduce the code block
300+
with "For example:". If more context follows the example, add "In the
301+
previous example,"" to the context.
302+
303+
**Example:**
304+
305+
.. list-table::
306+
:header-rows: 1
307+
308+
* - Before
309+
- After
310+
311+
* - .. list-table::
312+
:widths: 20 20 60
313+
314+
* - 404
315+
- Not Found
316+
- The requested resource does not exist.
317+
318+
* - 405
319+
- Method Not Allowed
320+
- The HTTP method is not supported for the specified
321+
resource. Keep in mind that each resource may only
322+
support a subset of HTTP methods.
323+
324+
.. example::
325+
326+
You are not allowed to ``DELETE`` the
327+
:opsmgr:`root </reference/api/root>` resource.
328+
329+
- .. list-table::
330+
:widths: 20 30 30
331+
332+
* - 404
333+
- Not Found
334+
- The requested resource does not exist.
335+
336+
* - 405
337+
- Method Not Allowed
338+
- The HTTP method is not supported for the specified
339+
resource. Keep in mind that each resource may only
340+
support a subset of HTTP methods.
341+
342+
For example, you are not allowed to ``DELETE`` the
343+
:opsmgr:`root </reference/api/root>` resource.
344+
345+
Procedures Inside Procedures
346+
----------------------------
347+
348+
Remove the nested procedure and add its contents to an ordered list.
349+
Start with a., b., c., d., and use i., ii., iii. for levels below that.
350+
Do not nest steps more than that.
351+
352+
**Example:**
353+
354+
.. list-table::
355+
:header-rows: 1
356+
357+
* - Before
358+
- After
359+
360+
* - .. procedure::
361+
:style: normal
362+
363+
.. step:: Open the Atlas Search index you want to update.
364+
365+
.. procedure::
366+
:style: connected
367+
368+
.. step:: Navigate to your Atlas Search tab.
369+
370+
.. step:: On the index you want to copy, click ``...`` in the :guilabel:`Action` column.
371+
372+
.. step:: Click :guilabel:`Edit With JSON Editor`.
373+
374+
.. step:: Copy the index.
375+
- .. procedure::
376+
:style: normal
377+
378+
.. step:: Open the Atlas Search index you want to update.
379+
380+
a. Navigate to your Atlas Search tab.
381+
b. On the index you want to copy, click
382+
:icon-fa5:`ellipsis-h` in the :guilabel:`Action` column.
383+
c. Click :guilabel:`Edit With JSON Editor`.
384+
385+
.. step:: Copy the index.

0 commit comments

Comments
 (0)