Scribd
Upload
37 views3 pages

Writing Guidelines: Microsoft Manual of Style: Topic Units Guidelines

Uploaded by

Andreea Dascalu
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as DOCX, PDF, TXT or read online on Scribd
37 views3 pages

Writing Guidelines: Microsoft Manual of Style: Topic Units Guidelines

Uploaded by

Andreea Dascalu
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as DOCX, PDF, TXT or read online on Scribd
You are on page 1/ 3

Writing guidelines

Tuesday, February 18, 2020


7:38 PM
 
Microsoft Manual of Style: https://docs.microsoft.com/en-us/style-guide/welcome/
 
Topic units Guidelines

General  Review every word that you use. Do not use marketing language to
create content, except in Get Started or the Home page.
 All sentences must end in a period, except those that have a file path.
 Use ordered lists for sequential information; use unordered lists in all
other cases.
 Try as much as possible to rewrite sentences, so that they don’t
exceed 13-15 words.
 When there are more than three items in a sentence, rewrite to
create an unordered list with a lead line.
 Ensure that content is aligned appropriately.
 Do not use inline links unless the link takes the user to something
that needs to be understood/performed before they can proceed from where they
currently are on the page.
 Remove titles like Overview, Introduction, Appendix. Integrate the
content from such topics as required.
 Read through a topic before you rewrite it and ensure that you have
the right audience in mind. There are many instances in our documentation where
we have placed the topics under the wrong nodes. Make note of where the topic
must be placed when you perform the content audit.
 Apply the required heading styles where it is inappropriate.
 VERY IMPORTANT: Ensure that topic hierarchy does not go beyond
three levels. Merge topics where it makes sense. For example, Prerequisite
topics on different pages.
 In case of Third Party products, search on Google to verify their
naming and usage on their company websites.
 Maintain consistency in how sections are structured. If there is
information on Linux and Windows in one topic, ensure that you provide
information for Linux and Windows in similar topics.
 In many cases, the landing page of a node lists a number of topics.
However, on validation, there are more topics within the node, which are not
listed on the landing page.
 Login is a noun; log in is a verb. Understand the difference. The same
with backup and back up.
 Provide the expanded version of an acronym followed by the
acronym in parentheses in its first occurrence on a page. Follow this up by using
the acronym on the rest of the page.
 Avoid groups of nouns. For example: Kubernetes content pack flows
and operations. Change this to "Flows and operations in the Kubernetes content
pack".

Titles  A title must be an exact indicator of the information contained in the


topic.
 Do no use words like manage, understand etc.
 All titles must be in sentence case. Use title case only in the case of UI
elements and proper nouns.
 The title in the left ToC must match the title and the case used on the
page.
 Use a verb form for title in case of procedures; noun form in case of
concepts.
 Do not use -ing (gerunds) of the verb in the title.
 Use acronyms in titles

Styles  Use boldface for UI elements.


 For commands, in Visual Editor, use the ‘computer code’ formatting
for paragraph style.
 For file names and directories, in Visual Editor, use the ‘computer
code’ formatting for paragraph style.
 For command output, in Visual Editor, use the insert ‘code block’
option.
 Use boldface for Boolean values like True, False etc.

Tables  Always include a lead line for the table.


 Cell headings must be in sentence case.
 Do not use bullets within table rows and columns.
 Do not merge cells.
 Have only one item per cell.

Concept  If it is a landing page, ensure that the content on the page is of value.
The landing page should not just contain a list of sub-topics.
 Ensure that a list of topics on the landing page contain all the sub-
topics.
 Avoid content in parentheses as much as possible.
 Use noun forms in the title. The same will apply to reference topics.

Procedure  Ensure that all procedures:


 Have a lead line where there is a concept ahead of the
procedure
 Have a self-explanatory title
 In case of a downloadable file, ensure that you have provided the
exact location/path from where the file must be downloaded and to where the file
must be placed.
 Ensure that the downloadable file is named accurately.
 Ensure that file names and file paths are accurate.
 Do not break up a procedure into sub-sections unnecessarily. As
much as possible, have a single procedure that covers a task end-to-end.
 Avoid sub-steps as much as possible. Have a clear-cut end-to-end
procedure. In addition, it causes issues when the page is converted to a PDF.
 Pay attention to Notes/Disclaimers/Important/Caution etc. Instead of
placing the information from the Note etc above or below a procedure, integrate
the information in the Note into the procedure itself.
 All screenshots must have a border (Micro Focus Blue color, 1px
thickness)
 Avoid words that cause ambiguity (for example, clean installation)
 If there is only one step in a section, there is no need to provide a
number to the step. In the same way, there is no need to provide a bullet when
there is a single point.
 Use <<File>>.zip and ZIP file accordingly. The same rules apply to TAR,
JAR etc.
 Avoid content in parentheses as much as possible.
 When writing a step, ensure that you start with the
consequence/result, followed by the action. For example, To back up the RPA
Workflow Designer's keystore, open a command prompt and enter the following
command:"
 Include the result of a step in the same step.
 Ensure that there are no gaps in the technical information. For
example, missing location, missing UI element.
 Maintain consistency across topics in terms of naming on UI
components. For example, do not use SA core in one topic and SA Core in another.

Related  Move inline links to Related topics as much as possible.


topics  Provide a clear description of the link being provided. Bad example:
For more information about the Support Matrix, see the Support Matrix.
 Make Related topics meaningful by providing the details within the
topic. For example: For the databases and operating systems supported by DCA,
see the Support Matrix.
 Ensure that every link provided in the Related topics adds value to
the content on that page.
 In case of sequential topics, ensure that you provide the Previous
topic and Next topic in the list. For example, in the Install and Upgrade nodes.
 

You might also like