Skip to content

Documentation Guidelines

When writing documentation for the Suite, there are some things to take into account.

As a general rule, use VSCode for editing the documentation file and make sure you have set it up properly since we have some linting extensions and stuff.

Running the documentation site

You can run a local copy of the site by:

Bash
1
2
cd docs/
docker-compose up

And then browsing to http://localhost:8080, the site will auto update when you make any changes.

Warning

When performing changes, take a look at the output for any errors or warnings.

Naming files

  1. All documentation files should be markdown .md
  2. File name must be a short version of its title.
  3. File name should not contain any prefix. (refactors are still pending)

Assets

  1. Pictures and other assets may be added into an assets directory next to the documentation file that uses it.
  2. When adding pictures, please run them through TinyPng for compression.
  3. If the asset was created by you, like a draw.io chart, please upload the source next to the asset as well.
  4. PNG images with transparent background are recommended when possible.

References

  1. When referencing assets or other doc files next to the documentation file, use relatives paths. i.e: assets/image.jpg, my-other-doc-file.md.
  2. When referencing assets or other doc files at a different level, using absolute paths is recommended. i.e /dotnet/modules/localization.
  3. When using absolute paths .md format is not used.
  4. References to headers within an article are possible, i.e
    1. Given a test.md file with a ## My Header Is This one may use this link test.md#my-header-is-this.

Markdown

  1. Use the ` character only for inline code, filenames, network addresses, etc.
  2. Do not use the ` character for titles, primary names, words, or library names (not package ids), etc.

.NET Namings

  1. Use the term .NET for referring to .NET Core or .NET 5.
  2. Use the term .NET Framework for referring to .NET Framework.
  3. Use the term ASP.NET Core for referring to the latest ASP.NET version.
  4. Use the term ASP.NET for referring to .NET Framework's one.