Wiki Guidelines

This page outlines the guidelines for creating any page on the Husky Robotics wiki. Every page on the wiki except for a select few must follow one of the standards outlined here. Please read the relevant page standard, especially the naming convention, before creating any new pages on the wiki, and follow them as closely as is reasonable. If you have any questions about what standard should be used for a given topic, please contact the wiki bureaucrats: Dylan Klavins. Some basic tips for page creation:
 * Always link the standard that the page is based on at the top of the page. This will aid anyone who is unsure how to create a similar page in finding the appropriate standard to follow.
 * Copy and paste the template page for that standard when creating your page. This will ensure consistency between all pages of a certain type and make your job easier!
 * Put links to your page in all the appropriate places before adding content to make absolutely sure you don't forget to do so! Your page is only useful if people can actually find it.
 * Refer to the example when you're unsure how to format a section. These examples will provide a good reference for how a page should look and function.

Major Page Formatting Standards
This section outlines a standard for each common type of page that will exist on this wiki. For consistency, readability, and navigability, most pages on the wiki should follow one of these standards. See special page standards for standards for less common page types. Every page should contain a reference to the standard it follows

Documentation Page Standard
Samples for Reference: Documentation Example |  PY2023 Documentation Page Template

Documentation pages make up the majority of the Current Documentation and Archive sections of the site, with the remainder of the documents in these sections being performance and design review reports and R&D project pages.

The purpose of a documentation page is to convey the design process used during the development of a specific system on the rover. Each documentation page should cover only the development of one mechanism, and should go into sufficient detail that the overall design can be reproduced and understood. Navigability is crucial for the documentation pages, so the page naming and format conventions must be strictly followed, and any time content in another documentation page is mentioned, that page should be linked.

Documentation Site Structure
Documentation pages should not be created, deleted, or moved on a regular basis, rather careful thought should be put into the organization of them at the beginning of every design cycle. Any changes to the page structure should be reviewed by relevant subsystem members before implementation.

Every rover will have an index page that contains links to every documentation page created for that rover, and any time pages are added or deleted this index page should be updated to reflect that.

Documentation pages that pertain to specific rovers and systems within those rovers should fall into a simple hierarchy with four levels.:
 * Top Level: Rover Page - Each rover will have a single documentation page covering the overall design concept of that rover.
 * Contains links to all level 2 pages
 * Focus on what major issues were being addressed and what challenges were encountered in making these work.
 * Should provide technical information relevant to the rover as a whole and any interactions between subsystems.
 * Level 2: Subsystem Pages - Each rover should have a single documentation for each of the technical subsystems: Arm, Chassis, Electronics, Science, and Software. Every rover will have these specific 5 level 2 pages and no others.
 * Contains links back to relevant parts of the rover page, and to level 3 component pages.
 * Focus on the overall operating principle of the subsystem and its performance objectives and characteristics.
 * Should provide details of the interactions between components within the subsystem, and an overview of the design intent behind the subsystem.
 * Should link only to documents key to the entire rover, like a global BOM and task management platforms
 * Level 3: Component Pages - Each subsystem within each rover should have pages for each component that makes up that subsystem. The number and grouping of these will vary subsystem to subsystem, and pages may be split and merged throughout the design process of a given rover, albeit after discussion with subsystem authorities.
 * These should contain the bulk of the highly technical information on the development and implementation of all systems on a given rover. This info should be left off of top level and level 2 pages to improve readability and reduce clutter.
 * Contains links back to any relevant sections of the subsystem pages and to any level 4 pages that may exist.
 * Contains an extensive and well maintained references section that links to important design and reference documents, including other wiki pages, pages on other Husky Robotics platforms, external websites, and publications.
 * Level 4: Special Topics - Any topics within a component page which require in-depth design work unto themselves which is fairly disjoint from the rest of the component and whose presence may clutter the component page may be allotted a special topic page. These should be created at component groups' discretion during the design process, as such special topics come up.
 * Format should closely mimic the level 3 format, with an increased focus on technical details.

Other documentation pages, such as those for rover peripherals or test equipment, should follow this format but be organized separately. Each may be allocated their own Level 2 or Level 3 page, depending on their scope. Research projects should follow the R&D Project Page Standard.

Naming Convention
All documentation pages are to be named according to the following standard:

 [Performance Year] Doc - [Subsystem] - [Project/Component] - [Any other specifiers] 

For the rover's main documentation homepage, the Subsystem section should simply say "Rover Home Page". Level 2 documentation pages should only include the subsystem name, level 3 should also include the project/component section, and level 4 pages should include all sections of the title format. For example:

PY2022 Doc - Arm - Elbow

PY2020 Doc - Rover Home Page

Page Sections and Usage
Any documentation page should contain the following sections, in the order shown below. Note that active projects, especially early in the design phase when they are far from complete, may not have all of these sections in their entirety, but the sections that do exist should not deviate from this standard in any significant capacity unless absolutely necessary.

Service Manual Standard
Samples for Reference: Service Manual Example |  PY23 Service Manual Template

Event Report Standard
Samples for Reference: Event Report Example

R&D Project Page Standard
Samples for Reference: R&D Project Page Example

Curriculum Page Standard
Samples for Reference: Curriculum Example

This is a standard for a page designed to teach members individual topics without their needing to work with a mentour (unless of course they have questions)

Rover Design Guide
Who is the audience for this material
 * Freshman/newer and less experienced members

Should we teach to standard design practices?
 * Not in curriculum for engineering practices, standards should be maintained in separate spaces
 * For communication resources we should teach standards

Possible ways to break down
 * Break down into UW course series topics?
 * Could take resources from those courses to use

Index Page Standard
Index pages are pages that contain almost exclusively a large list of links to any group of pages within the wiki.