dev.ContributingToTheWiki

Contributing to the Wiki

This page details the best practices on how to improve Tooll's documentation on the wiki.

Guidelines

Wiki pages should follow the following guidelines:

• Page names should start follow this convention: dev.PascalScale.md (Please don't use hyphens "-").
• Before creating new pages, please make sure a page covering a similar topic doesn't already exist.
• Please don't create pages describing operators (see Writing Operator Descriptors below).
• Avoid html formatting such as <br> unless necessary.

Use a proper editor

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:

1. In the wiki, click the Copy icon under "Clone this wiki locally"

2. Open a git-interface like Fork

3. Clone the repository (In Fork Ctrl+N)

4. Select a target folder

5. Clone

6. Open Visual Studio Code

7. File → Open Folder

8. Open a file

9. Toggle the preview icon to see a preview:

Writing operator descriptions

---

The wiki pages for operators are auto-generated based on the operators' descriptions within Tooll3. That means that any contributions made directly to that section of the wiki will be overwritten on a regular basis. If you want to contribute operator descriptions, you'll need to install the development environment and write them in-application.

Currently, T3 only supports plaintext within operator descriptions. This means it should be kept as readable as possible without Markdown formatting, ie. use minimal emphasis or bold text, and avoid images.

Throughout this guide, the [Time] operator will be used as an example.

Summary statement

---

Start with a one-line summary. It should quickly convey the function of the operator, and nothing more. Every library operator should have a one-line summary, even the simplest ones.

Guidelines:

• Keep it concise and to the point.
• Avoid padding text with phrases like "This operator does..." or "A handy tool to..."
• If an operator is an internal helper, begin the summary with "Internal helper."

Example: the [Time] operator

Returns the time elapsed since the beginning of playback.

Synonyms

---

The next line underneath the summary should be the word AKA: followed by synonyms for the operator name - any other terms that users might search for when looking for this operator. This mitigates the need for bloated SEO-style descriptions.

Guidelines:

• Separate words with commas.
• Use one-word synonyms only.

Example: the [Time] operator

AKA: clock, seconds, bars

Further details

---

Operators that need a more in-depth explanation can have as many paragraphs as necessary in this section. These paragraphs should describe, in detail, how to use the operator. This explanation is not necessary for more simple operators.

Generally there's no need to explain the exact internal logic behind how an operator works. Most of that information is not necessary in knowing how to use the operator - and anyway, a curious individual could just open it up and look inside to find out! Some operators in T3 can behave erratically or unintuitively due to the way their internal logic works. In these cases, it might make sense to mention why this behavior occurs - but it would be much better to patch the operators to be more intuitive.

Guidelines:

• Avoid first- or second-person pronouns ("I like to do A", "This op works best if you do B").
• Avoid subjective descriptions ("This op creates an interesting effect").
• Include long-form descriptions of parameter functions here, rather than in the parameters' descriptions.
• No need to refer to "The operator" or "The (function)".
• Not everything can be explained through text! Sometimes examples or videos are necessary.

Example: the [Time] operator

Will pause when playback is stopped, unless the "LocalFxTimeInBars" mode is selected.

Parameter descriptions

---

Individual parameters can have their own descriptions. These are only necessary if the name of the parameter is insufficient to describe its function. Parameter descriptions should be kept short - more detailed explanations can go in the main operator description.

Guidelines:

• Keep descriptions concise and to the point.
• Don't describe parameters that are self-evident ("Radius: sets the radius of the sphere").

Example: the [Time] operator

Mode: (no description needed) SpeedFactor: Rate at which time increases.

Tips & advice

---

The Tips section at the bottom of the description is for more subjective content. Advice on optimization, interesting combinations to try, or other recommendations can be made here. Tips should be written in bullet-list format.

Guidelines:

• Tips can (but don't have to) be phrased like instructions. This means second-person pronouns are fine.
• First-person pronouns should still be avoided. Tips can generally be rephrased to remove them ("I like to set A to 3 and tweak B, it creates an interesting effect!" -> "Try setting A to 3 and tweaking B, it creates an interesting effect!")

Example: the [Time] operator

Tips:

• If you want to restart the timer during playback, try the [Accumulator] operator.

All together now!

---

Below is the full example description for the [Time] operator. (Note that parameter descriptions are not shown - they have their own section within the application.)

Returns the elapsed time since the beginning of playback.

AKA: clock, seconds, bars

Will pause when playback is stopped, unless the "LocalFxTimeInBars" mode is selected.

Tips:
- If you want to restart the timer during playback, try the [Accumulator] operator.