dev.ContributingToTheWiki
On this page we collect best practices on how to improve Tooll's documentation on the wiki.
Wiki pages should follow the following guidelines:
- Page names should start follow this convention:
dev.PascalScale.md(Please don't use hyphons "-"). - Before creating new pages please make sure a page covering similar topic doesn't already exist.
- Please don't create pages describing Operators because these are automatically created.
- Avoid html formatting
<br>unless necessary.
Working on the github website is okay for quick fixes, but for better ease of use, you should download the wiki and use Visual Studio Code: It has an awesome inline editor that also allows linking between pages:
To do so:
- In wiki click icon under "Clone this wiki locally"
-
Open a git-interface like Fork
-
Clone the repository (In Fork Ctrl+N)
-
Select a target folder
-
Clone
-
Open Visual Studio Code
-
File → Open Folder
-
Open a file
-
Toggle the preview icon to see a preview:
- Be short an concise
- Start with a very short summary
Take this example from [SetContextVariable]:
Writes a float value to the context float variable dictionary.
Avoid intro statements like...
❌ This Operator does divide two ints
✔ Divides two integer values.
❌ This is the Operator that does ...
❌ A nice ...
✔ Give context if an operator is internal
An internal helper to ....
- ⚠ Only add descriptions to operators you're absolutely sure you understand what it's doing. If in doubt ask @pixtur on discord. Always remember: An incorrect or misleading documentation is worse than no documentation.
Only add details the are not obvious:
❌ Radius sets the radius of the blob.
Since the wiki-documentation is directly used inside Tooll, we have to restrict the formatting to make it as readable as possible without markdown formatting. (Although eventually we should add markdown formatting for this).
An example for how the formatting should look like:
Headline
-------
Some description
- line A
- line B
Avoid images.