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](mailto: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](https://www.markdownguide.org/basic-syntax/)

## 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.