Write documentation

Markdown and structure

All documentation for Trader Core is contained in the articles subfolder of the project Trader.Core.Documentation using markdown files.

• Arrange the markdown files in the folder tree you want represented by the documentation menu.
• Each subfolder should contain an index.md file that will be used as the default article for that subfolder
• Make sure you regenerate the TOC

Extract the Modules documentation

Caution

Do not manually edit any markdown under the Modules folder.

The modules folder is populated with documentation that is maintained in the modules themselves. If you edit this content directly in the documentation project, your changes will be overwritten.

Follow these steps to copy the module documentation into the Modules subfolder.

• Locate the Utils\TraderCoreLowCode\Commands folder in the solution
• Run the project Update-Documentation
• Any files in the docs subfolder of each module will be copied into the Modules directory.
• The index.md file of the Modules directory will be updated with any information available in the IConfigureModule instance of the project.
• The TOC.yml file will be recalculated for you based on the structure of the articles directory

Generate the TOC

Caution

Do not manually edit the toc.yml file.

The documentation menu on the left is based on the toc.yml file located in the root of the documentation project. Nobody wants to manually generate the TOC file. Who has time for that.

• Locate the Utils\TraderCoreLowCode\Commands folder in the solution
• Run the project Update-Toc
• The TOC.yml file will be recalculated for you based on the structure of the articles directory

Essential authoring tools

Markdown uses plain old text files. That makes them easy to create but clunky to manipulate. Some key luxuries like WYSIWYG and spell-checking are sacrificed in the process.

The Docs authoring pack for VS Code makes life much easier by addressing these short-falls.

• Use VS Code - it has a nice text/preview dual view mode so you can see the document as you create it
• Install Docs Authoring Pack extension in VS Code
• Access the extensions through the command pallette or use the shortcut ALT + M to show the Markdown authoring menu

Caution

Make sure you set your spell-check language to en-GB.

Markdown authoring menu

This contains heaps of stuff to make writing markdown a breeze.

Helpful links

Link	Description
Docs Markdown reference	This article provides an alphabetical reference for writing Markdown for docs.microsoft.com (Docs).