General Tips

This topic covers some general tips.

File Naming

Rules

  • No spaces or punctuation characters. Use hyphens to separate the words in the file name.
  • Use all lowercase letters.
  • No more than 80 characters - this is a publishing system limit.
  • Use action verbs that are specific such as develop, buy, build, troubleshoot. No -ing words.
  • No small words - don't include a, and, the, in, or, etc.
  • All files must be in markdown and use the .md file extension.
Note

The names of the folder structure, files, pictures and videos must be in English.

Examples

Topic title Naming
Select a Company ui-how-select-company.md
Enter Criteria in Filters ui-enter-criteria-filters.md
Troubleshooting: Record Locked by Another User ui-troubleshoot-record-locked-another-user.md
Changing Basic Settings ui-change-basic-settings.md
Sales sales-manage-sales.md
Set Up Currencies finance-setup-currencies.md

Topic Titles

  • Use imperative verb form for step-based topics (Pay vendors).
  • Use gerund verb form for conceptual, non-step topics (Paying Vendors).
  • Use nouns for highest-level topics (Sales.

Icons

Use the following icons with tooltips in image properties provided in the demo media folder:

  • Show more options Show more options icon
  • Tell Me Lightbulb that opens the Tell Me feature
  • New entry Plus icon that creates a new entry
  • Toggle Expand / Collapse All Toggle Expand / Collapse All icon
  • Expand row Expand row icon
  • Collapse row Collapse row icon
  • Select Picture Select picture icon
  • Search Search icon
Note

In some list views there is a Search icon, not to be confused with Tell Me.

Screen Shots - Less is More

If you want to explain processes or concepts, you should include some diagrams, and other visuals. If you can't find the words to clearly explain what you want the reader to do, a screen shot might also help. Generally, you don't need to include screen shots for UI elements because

  1. they need to be changed every time your UI changes, otherwise they become out of date and your readers get confused.
  2. if the UI you're writing about is skinnable or otherwise configurable, the person who makes the screen shots might have a different layout than the default, which will again confuse the reader.
  3. screen shots can't be translated. If your documentation is translated into multiple languages, your translators will have to reproduce the screen shots in the target language.
  4. screen shots are bad for accessibility. Sight-impaired users rely on text-to-speech to read your documentation. Screenshots are not conducive to screen readers, so you'll need to write good text anyway. That's why we recommend using screen shots sparingly and only when necessary for clarity.

Process-oriented vs. Task-oriented

Try to write process-oriented instructions to help users understand concepts and processes instead of describing every single object page.

If steps are important, writing can of course also be task-oriented.

Metadata

Each markdown file can define metadata above the first header. They can define alternative title for the page or show page description in the search result. For some applications like Dynamics 365 Finance & Operations, they must be used to add information like language and content area.

A simple example of title and description implementation:

---
    title: Alternative Title for Browser and Search
    description: Global search result description (not for local search). 
---