Skip to content

Commit b228352

Browse files
jeff-allen-mongosarah-olson-mongodb
jeff-allen-mongo
and
sarah-olson-mongodb
authored
Add information typing pages (#146)
* DOCSP-23913: Add info typing POC * DOCSP-23914: Add info types to index file * DOCSP-23914: added information types to snooty.toml * DOCSP-23914: Add work in progress note * DOCSP-23914: edit note * add code block to concept page * add heading for code example * tweak heading * wording * change Tasks > Get Started * add on this page to IA pages * remove periods from step titles * single-source general guidance * address review feedback * edit * add info typing to style guide page * change to note * move file location for information types * update file location for sub-pages * update file path for snooty.toml * test * fix includes * fix snooty.toml * fix snooty.toml * reset changes to release notes guidelines * typos * address review comments * address CC review comments * add DITA info * fix typo in filename * standardization * add prototype page in toc * typo fix and snooty.toml update * move DITA info above table * add admonition title * update task description * single source task description --------- Co-authored-by: Sarah Olson <[email protected]>
1 parent f46099c commit b228352

File tree

11 files changed

+412
-1
lines changed

11 files changed

+412
-1
lines changed

‎snooty.toml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
44
"https://www.mongodb.com/docs/ops-manager/current/objects.inv"
55
]
66
toc_landing_pages = [ "/style-guide", "/writing", "/style", "/terminology", "/terminology/general-term-guidelines",
7-
"/screenshots", "tutorials", "reference", "practices", "/tutorials/screencapture-tool" ]
7+
"/screenshots", "tutorials", "reference", "practices", "/tutorials/screencapture-tool",
8+
"/style-guide/information-types/index", "/style-guide/information-types/prototypes" ]
89

910
[constants]
1011
rst = "reStructuredText"

‎source/includes/info-typing/concept-overview.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
A concept page helps a user learn about a concept or new feature. The page intends to
2+
answer the following questions:
3+
4+
- "What is this?"
5+
6+
- "Why do I care?"
7+
8+
- "How does this work?"
9+
10+
The audience includes users who have never used a particular feature or
11+
command.

‎source/includes/info-typing/fact-general-guidance.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
.. note::
2+
3+
This page provides general guidance and examples for Information
4+
Types. Verify the correct and consistent guidelines for each product
5+
with your team.

‎source/includes/info-typing/fact-learn-more.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
This section appears on every information typed page. It does not
2+
replace inline linking, but is intended to augment the information on
3+
the page with related concepts, tasks, and reference material. Use it to
4+
link related pages that are not already linked above, such as reference
5+
information, technical deep dives, less commonly used task pages, or
6+
related concepts.

‎source/includes/info-typing/task-overview.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
A task page instructs a user on how to accomplish a particular goal. A
2+
task page can be written for users with any level of experience with
3+
MongoDB. Users might approach a task for the first time, have limited
4+
experience, or need a refresher. A task page should contain all the
5+
necessary information for someone to complete the task, any necessary
6+
conceptual information, prerequisites, steps, and expected results.

‎source/style-guide.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,10 @@ MongoDB external and internal customers.
3838
MongoDB products. You can use these basic guidelines,
3939
however, when writing release notes for any product or service.
4040

41+
:ref:`information-types`
42+
Provides guidelines for information types to identify the goals of a
43+
page and its audience.
44+
4145
:doc:`/style-guide/seo-guidelines`
4246
Provides guidance for optimizing your documentation pages for
4347
search.
@@ -58,6 +62,7 @@ MongoDB external and internal customers.
5862
/style-guide/screenshots/index
5963
/style-guide/error-message-guidelines
6064
/style-guide/release-notes-guidelines
65+
/style-guide/information-types/index
6166
/style-guide/seo-guidelines
6267
/style-guide/revision-history
6368

‎source/style-guide/information-types/index.txt

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
.. _information-types:
2+
3+
=================
4+
Information Types
5+
=================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
.. include:: /includes/info-typing/fact-general-guidance.rst
14+
15+
The following sections describe information typing and provide
16+
prototypes that show how to apply this strategy to our documentation.
17+
18+
What is Information Typing?
19+
---------------------------
20+
21+
Information typing categorizes content by type based on your audience's
22+
goals. Throughout the writing process, information typing helps keep the
23+
information that you write focused on those goals.
24+
25+
Additionally, information typing accomplishes the following goals:
26+
27+
- Separate content into categories and delivers roughly one type at a
28+
time.
29+
30+
- Account for the purpose of a page before you write it.
31+
32+
- Answer the user question "why do I care?" or "what does this mean for
33+
me?" quickly.
34+
35+
- Use a suggested format to help you get started on a blank page.
36+
37+
What Information Types Do We Use?
38+
---------------------------------
39+
40+
.. note:: DITA Document Types
41+
42+
The information types used in MongoDB documentation are similar to
43+
`DITA Document Types
44+
<http://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part3-all-inclusive/archSpec/technicalContent/dita-technicalContent-InformationTypes.html#dita_technicalContent_InformationTypes>`__.
45+
While we do not impose the same {+rst-abbrev+} requirements that are
46+
used in DITA, the high-level purposes of corresponding content types
47+
are largely the same.
48+
49+
Currently, some teams use the following information types:
50+
51+
Concept
52+
.. include:: /includes/info-typing/concept-overview.rst
53+
54+
Reference
55+
A reference page delivers granular details about a topic. The audience
56+
includes experienced users. Reference pages may describe the use of a
57+
method, operator, or database command.
58+
59+
Task
60+
.. include:: /includes/info-typing/task-overview.rst
61+
62+
.. toctree::
63+
:titlesonly:
64+
65+
/style-guide/information-types/prototypes

‎source/style-guide/information-types/prototypes.txt

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
===========================
2+
Information Type Prototypes
3+
===========================
4+
5+
.. contents:: On this page
6+
:local:
7+
:backlinks: none
8+
:depth: 2
9+
:class: singlecol
10+
11+
.. include:: /includes/info-typing/fact-general-guidance.rst
12+
13+
The following pages show prototypes for the information types used by
14+
some documentation teams:
15+
16+
:ref:`meta-concept-prototype`
17+
Helps a user learn about a concept or new feature.
18+
19+
:ref:`meta-reference-prototype`
20+
Delivers granular details about a topic.
21+
22+
:ref:`meta-task-prototype`
23+
Helps a user do a job.
24+
25+
.. toctree::
26+
:titlesonly:
27+
28+
/style-guide/information-types/prototypes/concept
29+
/style-guide/information-types/prototypes/reference
30+
/style-guide/information-types/prototypes/task

‎source/style-guide/information-types/prototypes/concept.txt

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
.. _meta-concept-prototype:
2+
3+
======================
4+
Concept Page Prototype
5+
======================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. include:: /includes/info-typing/fact-general-guidance.rst
14+
15+
.. include:: /includes/info-typing/concept-overview.rst
16+
17+
The title is typically a noun or noun phrase.
18+
19+
A concept page begins with a brief introduction that summarizes its
20+
contents, often called a short description. The short description
21+
explains a little about the concept and why the audience should care
22+
about it.
23+
24+
Command Syntax
25+
--------------
26+
27+
Optional.
28+
29+
If it's appropriate, you may include a code-block with a copyable
30+
prototype to familiarize users with command syntax.
31+
32+
.. code-block:: javascript
33+
34+
db.collection.<method>( {
35+
/* command fields */
36+
} )
37+
38+
After the code block, provide a link to the corresponding
39+
:ref:`reference <meta-reference-prototype>` or :ref:`task
40+
<meta-task-prototype>` page to provide readers with complete examples
41+
and behavior details. When possible, use includes to single-source code
42+
examples across related concept, task, and reference pages.
43+
44+
.. note::
45+
46+
For concept pages that have multiple linked tasks, the code example
47+
should show the most common task we expect users to look for.
48+
49+
Use Cases
50+
---------
51+
52+
This section includes a collection of use cases to explain "What do I do
53+
with this thing?" In general, use cases are short descriptions about how
54+
to use a feature. They set expectations for when and how you might use a
55+
feature and what differentiates this feature from other options.
56+
57+
Behavior
58+
--------
59+
60+
This section includes information you need to know before using a
61+
feature. It can be as long or short as appropriate. Some examples of
62+
technical details include:
63+
64+
- Performance considerations and behavior alerts
65+
66+
- Support for a feature (for example, sharded cluster support or
67+
Versioned API compatibility)
68+
69+
- Version support
70+
71+
Get Started
72+
-----------
73+
74+
Link to the most common task pages related to this concept. Linking to
75+
all task pages isn't necessary here. The goal of this section is to make
76+
sure users can easily find common related tasks.
77+
78+
- Link one
79+
- Link two
80+
- Link three
81+
82+
Details
83+
-------
84+
85+
This section is a brief unpacking of the technical details. It can be as
86+
long or short as appropriate. Generally, the information in this section
87+
is supplemental and should not be a major factor in a user's decision to
88+
use a feature.
89+
90+
Learn More
91+
----------
92+
93+
.. include:: /includes/info-typing/fact-learn-more.rst

‎source/style-guide/information-types/prototypes/reference.txt

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
.. _meta-reference-prototype:
2+
3+
========================
4+
Reference Page Prototype
5+
========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. include:: /includes/info-typing/fact-general-guidance.rst
14+
15+
A reference page provides quick information to experienced users of a
16+
product. Reference pages may describe the use of a method, operator, or
17+
database command. Release notes are another example of reference page.
18+
19+
Usually, the title of a reference page is the name of the command, operator, or
20+
method it describes.
21+
22+
Definition
23+
----------
24+
25+
A reference page begins with a brief introduction summarizing its
26+
contents, often called a short description. The short description
27+
explains a little about how the reference material is used, and may link
28+
to a concept or task page.
29+
30+
Syntax
31+
------
32+
33+
This section includes the sample syntax with the required parameters.
34+
35+
.. code-block:: javascript
36+
37+
db.adminCommand(
38+
{
39+
addShard: "<replica_set>/<hostname><:port>",
40+
maxSize: <size>,
41+
name: "<shard_name>"
42+
}
43+
)
44+
45+
Command Fields
46+
--------------
47+
48+
The command takes the following fields:
49+
50+
.. list-table::
51+
:header-rows: 1
52+
:widths: 20 20 10 60
53+
54+
* - Field
55+
56+
- Type
57+
58+
- Necessity
59+
60+
- Description
61+
62+
* - Parameter
63+
64+
- String
65+
66+
- Required
67+
68+
- String
69+
70+
Behaviors
71+
---------
72+
73+
Optional.
74+
75+
Behaviors should apply only to the operator described on this page.
76+
77+
Examples
78+
--------
79+
80+
Optional.
81+
82+
This section could contain examples of the most common use cases. Use
83+
includes for Reference and Task page examples, so we write the examples
84+
once, present them consistently throughout the documentation, and can
85+
update them easily.
86+
87+
If an example is shared between task and reference, you should write it
88+
as an include.
89+
90+
Learn More
91+
----------
92+
93+
.. include:: /includes/info-typing/fact-learn-more.rst

0 commit comments

Comments
 (0)