Meta Wiki

This page provides standards and best practices to follow while viewing and making changes to the wiki. This page should be reviewed before anyone modifies pages on the wiki.

• Author: Alex Wilkes <adw4236@rit.edu>

Navigating the Wiki

The wiki is easiest to navigate while viewed on the GitHub wiki. The _Sidebar.md is the directory of all pages that are accessible on the wiki.

While navigating the wiki, if you have any questions about the content, you should first reach out to the individual labled as the subject matter expert if they exist, followed by the author of that page. You can also check the git commit history to see exactly who wrote the part you are reading if needed.

If at any point while using the wiki, you think of the following, a GitHub issue should be created and tagged as a wiki enhancement.

• Grammar or spelling mistakes
• Confusing content
• Additional / missing content
• Additional pages
• Broken links / images

If the change you are looking to do is very minor, it is acceptable to make the change yourself rather than opening up a github issue.

Editing the Wiki

It is very important that the content on this wiki is written from the assumption that the reader doesn't know anything about any of the technology used. This project has a history of changing hands and every future team needs to have as much information presented to them as possible.

The wiki is a git repo in itself and as such, any edits will be version controlled using the same standards that would apply to code. Comments about what was changed should be left with each commit.

Changes do not need to have pull requests or reviews, however all changes should be proofread for spelling and grammar before being finalized.

Whenever any change is made to the wiki, it is critical all team members are notified of the changes. The team members themselves can decide if the change requires their attention or not.

Page Formatting

Every page should begin with a brief description of the content that can be found on the page. This description should also include a team member that can be treated as a subject matter expert on the information in that page who can be contacted if needed. If this is different from the author, that should be noted. See the header section of this page for an example of how this section should be formatted. This should be mirrored on every page.

The formatting of the content on any given page should be broken down as much as possible using subheaders, bold words, and bullet points where applicable. Information should be detailed but be easy to skim in the future.

Specific formatting rules

• Lines - Should never exceed 100 characters long. Continue paragraphs on a newline.
• Headers - Should always use the # format instead of the dash format. The pounds should always be followed by a space before the text of the header.
• Links - Should never be "raw" and should always use the [Description](URL) format.
• Images - Should always contain alt text and should exist in the repository, don't link to outside images. These images can be stored in the /images folder.

The raw markdown text should be just as readable as the generated version, use whitespace as you need to make the text as readable as possible.

In general refer to these markdown best practices

Editing Existing Pages

The content of pages should always be updated at the same time changes are made to the code. If any content is out of date, a GitHub issue can be created for wiki modifications ass well and should be tagged appropriately.

Subject matter experts should be consulted if major changes are to be made to a wiki page. If significant changes are being made to a page, the individual making those changes should add themselves as an author to the page. If the majority of the content on this page is being changed, the previous author(s) can be removed.

Creating New Pages

A new page should be created whenever new content is needed and it does not belong in any existing pages. New pages can also be created to split up the content of an already existing page that has become bloated. In this case, pages should not be deleted, but rather sub-pages should be created, and only some content should be moved.

When creating a new page, it should first and foremost be added to _Sidebar.md. If a page is being broken up, the original entry in _Sidebar.md should be split up, maintaining its current link. The new pages should become sub-points of the current page's entry. It may be acceptable to create subsections within the current sections to help increase organization in the future.

The following is a template that can be used to seed a new page.

This page provides information about {description of page}.

- Author: {Name} <[{Email}](mailto:{email})>
- Subject Expert: {Name} <[{Email}](mailto:{email})>

# {First Title}
... Content

What should be on the Wiki

When deciding weather content should be placed on the wiki, there are a few simple questions that should be answered.

1. Is this content useful to other developers?
2. Would this content be useful to a completely new team?
3. Is there no way to automatically generate this content?
4. Have there been discussions within the team about this content already?

If the answer to any of these questions was no, then the content likely should not be part of the wiki. Likewise, all content that answers yes to all of these questions should have an entry on the wiki.