From 32a215c290798681d1b302f948cf490790650580 Mon Sep 17 00:00:00 2001 From: aburt2 <32888184+aburt2@users.noreply.github.com> Date: Wed, 8 Nov 2023 13:50:41 -0500 Subject: [PATCH] added basic contribution guide, updated search plugin to search header level 3., updated wording and justifications for requirements --- docs/Contribution.md | 17 ++++++++++++++++- docs/Technical Requirements and Constraints.md | 14 +++++++------- docs/index.html | 2 +- 3 files changed, 24 insertions(+), 9 deletions(-) diff --git a/docs/Contribution.md b/docs/Contribution.md index 5275746..62f30b6 100644 --- a/docs/Contribution.md +++ b/docs/Contribution.md @@ -1,3 +1,18 @@ # Contribution Guide -TBD \ No newline at end of file +The guide offers general rules and guidelines for pushing changes to the documentation site. We accept pull requests on [github](https://github.com/IDMIL/tstick-docs) for new pages/sections and major/minor edits to existing pages. The site is powered by Docsify. We recommend reading their [documentation](https://docsify.js.org/#/?id=docsify) for an understanding of how it works. Each page is written as a markdown file. + +## General Rules +1. Check how the page renders before submitting pull requests. [Docsify's Quick start guide](https://docsify.js.org/#/quickstart) shows how to run docsify locally to preview sites in your browser. +2. Add your page to the _sidebar.md in the appropriate location so that it shows up in the sidebar. +3. Ensure your pages are readable in both light mode and dark mode. + +## New Page/Section Guidelines +1. Include description of page/section in the pull request. +2. Only ONE new page/section per pull request. +3. Check the structure of other similar pages for inspiration. +4. Avoid table of content trees with a depth of greater than three. (ie: main page -> subpage -> subpage, depth = 3) + +## Major/Minor Edits Guidelines +1. Describe reason for the edit in the pull request. +2. Only have ONE major edit per pull requests. You may include multiple minor edits in a single request. \ No newline at end of file diff --git a/docs/Technical Requirements and Constraints.md b/docs/Technical Requirements and Constraints.md index cabd3af..2e3b39d 100644 --- a/docs/Technical Requirements and Constraints.md +++ b/docs/Technical Requirements and Constraints.md @@ -23,7 +23,7 @@ Control and Communication System of the T-Stick is the set of hardware and softw |----|----|----| | **1** | **Control System** | | | 1.1 | The control rate of the system should be at least 1000HZ and will be no slower than 200Hz. | Test | -| 1.2 | Continuous signals should have a wireless signal rate of at least 100Hz and will be no slower than 50Hz. | Test/Analysis | +| 1.2 | Continuous signals will have a wireless signal rate of at least 100Hz. | Test/Analysis | | 1.3 | Wireless Signal Latency will be below 10ms. | Test/Analysis | | 1.4 | Wireless Signal Jitter will be below 2ms. | Test/Analysis | | 1.5 | The communication system will send any errors experienced by other subsystems to the user. | Demonstration | @@ -31,13 +31,13 @@ Control and Communication System of the T-Stick is the set of hardware and softw | 1.5.2 | The communication system will send errors experienced by the power system to the user, excluding errors that cause a complete power delivery failure. | Demonstration | | 1.5.3 | The communication system will send errors experienced by the control and communication system to the user. | Demonstration | -#### 1.1: The control rate of the system should be at least 1000HZ and will be no slower than 200Hz.. +#### 1.1: The control rate of the system should be at least 1000HZ and will be no slower than 200Hz. 1000Hz allows responsive control of the T-Stick. -#### 1.2: Continuous signals should have a wireless signal rate of at least **100Hz** and will be no slower than 50Hz. +#### 1.2: Continuous signals will have a wireless signal rate of at least 100Hz. -INSERTJUSTIFICATIONHERE +Wireless signal rates below 100Hz are not desired. Slow wireless rates have lead to poor and inconsistent performance when paired with libmapper. #### 1.3: Wireless Signal Latency will be below 10ms. @@ -45,7 +45,7 @@ Wireless latency for signals need to be below 10ms for continuous signals to hav #### 1.4: Wireless Signal Jitter will be below 2ms. -Jitter should be reasonably low for a consistent wireless speed. +Jitter should be reasonably low for a reliable and robust wireless performance. #### 1.5: The communication system will send any errors experienced by other subsystems to the user @@ -168,9 +168,9 @@ The manufacturability Requirements are all the requirements related to the manuf | 5.6 | The final assembly and repair of the T-Stick will be possible using only a soldering iron, wire stripper/cutter, heat gun, saw, and hex key. | Demonstration | | 5.7 | The T-Stick will use common readily available parts and materials. | Demonstration | -#### 5.1: The T-Stick will follow the design guidelines and requirements outlined in Sections 1 and 2 of the [T-Stick Design Guidelines](./Technical%20Requirements%20and%20Constraints/T-Stick%20Design%20Guidelines.md). +#### 5.1: The T-Stick will follow the design guidelines and requirements outlined in Sections 1 and 2 of the [ T-Stick Design Guidelines](./Technical%20Requirements%20and%20Constraints/T-Stick%20Design%20Guidelines.md). -standardisation of design… +Sections 1 and 2 of the T-Stick design guidelines outline the physical constraints that make up the T-Stick. If new designers which to make T-Sticks these should be followed to maximise playability of older pieces. Note that due to the rapid changes in the hardware space and firmware changes to the T-Stick it may not be possible to design a T-Stick that is identical to a previous design. #### 5.2: The physical design documentation will include a bill of materials. diff --git a/docs/index.html b/docs/index.html index b1b8cbf..3fcff29 100644 --- a/docs/index.html +++ b/docs/index.html @@ -45,7 +45,7 @@ placeholder: 'Type to search', noData: 'No matches found.', // Headline depth, 1 - 6 - depth: 2, + depth: 3, } };