Table of Contents
Tip

The docs as explained here are used in multiple projects, but documented only once for better maintenance. When applying this to other projects, remember that some things such as the name, repository, or paths are a bit different.

Documentation Conventions

The following conventions should help all docs contributors work together.

Images / Files / Assets

When using files, especially images, please follow these conventions.

1. Remember: Case Sensitive when Hosted

Be aware that the final docs will be hosted on github, which is case-sensitive.

  1. So MyImage.png and myimage.png are different files
  2. This is important when you're linking to files
  3. Always use lower-case file names
Note

If you accidentally get this wrong (eg. MyImage.png), and linking myimage.png it will work on your IIS/Windows, but not when finally hosted on Github.

2. Put Files Close to Where They Are Used

Put all files in the assets folder below the page where they are used.

  1. This makes it easier to find the files when you're editing the page.
  2. It also makes it easier to move the page to a different location.
  3. This also helps to "see" when files are not used any more.
  4. Only use files in the "own" asset folder.
  5. Don't use files from far-away asset folders.

3. Use Relative Paths

  1. ./assets/myimage.png or assets/myimage.png
  2. Rarely ../assets/myimage.png (only if you're in a sub-folder), but the file is still part of the same topic and should be reused

Documentation Tags

If you find such tags in a documentation, this means that whatever you are reading is marked because it's not done, needs more documentation or whatever (or that we forgot to remove the marker).

  • wip - This tag means Work-In-Progress.
  • todoc - This means that the feature exists, but needs documentation - you could help contribute :).
  • todo - This means that something should be done some time.

Creativity and Contribution

There's no hard and fast rule about how you create or edit images and videos. Any contribution is welcome. Feel free to use tools that you're comfortable with. For instance, Windows Screen Snippet is a fast and easy tool for creating and saving files. Remember, the goal is to make the documentation as clear and helpful as possible.


Main Author

Daniel Mettler, @iJungleboy [MS MVP, Oqtane Core Team]

Content Management Expert, Chief Architect of 2sxc and cre8magic.
Forged in the jungles of Indonesia, lives in Switzerland , loves Oqtane 🩸 & 2sxc 💜.

LinkedIn | Discord: @iJungleboy | Twitter: @iJungleboy | Github: @iJungleboy

Edit this page