Wiki Guidelines

Documentation Guidelines

 * Any documents which are not relevant to current rover work should be moved to the archive

What and When to document, and who does it

 * Highlights of each individual's activity should be noted down by subgroup leads in meeting minutes for every meeting
 * This can be done at the end of a meeting or asynchronously after the meeting
 * Major milestones, major decisions, and important design documents should be compiled from minutes into documentation entries as per the documentation standards as soon as they are completed.

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

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.

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

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.