This topic covers some general tips.
- 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.
The names of the folder structure, files, pictures and videos must be in English.
|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|
|Set Up Currencies||finance-setup-currencies.md|
- 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.
Use the following icons with tooltips in image properties provided in the demo media folder:
- Show more options
- Tell Me
- New entry
- Toggle Expand / Collapse All
- Expand row
- Collapse row
- Select Picture
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
- they need to be changed every time your UI changes, otherwise they become out of date and your readers get confused.
- 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.
- 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.
- 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.
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). ---