-
Notifications
You must be signed in to change notification settings - Fork 1
Writing The Wiki
This page contains a set of guidelines for writing parts of this wiki. They exist to ensure the wiki is consistent, and well-formatted.
The wiki is written using Github-Flavored Markdown, and utilizes some "advanced formatting", and is stored in its own, separate Git repository, available at https://github.com/galk-research/pddlsim.wiki.git.
To clone the repository using SSH, run:
git clone git@github.com:galk-research/pddlsim.wiki.gitYou can then edit the wiki locally, using your favorite text editor, and submit the changes using Git.
You can of course, use any Markdown or text editor of your choosing, however we ask that you do not use Github's website to submit changes to the wiki. Github's website will force changes to the document names and directory structure of the wiki automatically, which is undesirable.
Start case, meaning every single word gets its first letter capitalized. This is to avoid the ambiguity caused by having no standard definition for title case.
To organize documents at the source level, different documents will be in different folders, such as "Contribution", for documents relating to contribution, "Usage", for documents that are part of the user's guide, etc. If needed, you may make a new folder, or folders, for a given document to reside in. Ideally though, folders should be broad as to encompass many documents, instead of only being fit for one or two.
Because the wiki, once uploaded to GitHub, is flattened, having two documents with the same name, but in different locations, is problematic, beyond being sometimes confusing. Avoid this.
Because the name of the document acts as a kind of "heading", all other sections in a wiki document should start from heading level 2. All section names should be in sentence case.
Do not manually wrap the text. Rather, every single paragraph should get its own line, and text should ever appear as wrapped due to soft wrapping.
This makes it so there is no need to run any code after every single change to the wiki, to make all documents conform to a given line width.
If a given code block uses a language that isn't highlighted by GitHub (such as CDDL, used in the RSP Latest Specification page), don't elide its language. Taking the RSP specification page for an example again, instead of writing:
```
problem-setup-response = {
domain: text,
problem: text,
}
```Write:
```cddl
problem-setup-response = {
domain: text,
problem: text,
}
```When the wiki is built on GitHub, all structure is flattened. For example, to link to the page Contribution/Development Setup.md, write:
[...](Development-Setup)Where ... is replaced by the link text. Note how the Contribution/ folder doesn't appear in the relative link, as the wiki is flattened on GitHub. Also note how the space in the document name was replaced with a -, and how the file extension .md was removed outright.
This guideline is mainly to make the review of changes easier. Changes should be motivated by a real problem, instead of arbitrary style preferences, and should be isolated, instead of changing many different things at once.