Mach 30 Weekly Hangout Jan 31, 2013
Discussion Topic: Shepard v1.0 Documentation Review
Attending: J., Jeremy, Chris, Aaron, Juli, Greg
Start: 21:05 EST
End: 23:00 EST
Minutes:
- Jeremy - We would like to review the Shepard documentation to ensure its correctness and completeness so that it can be used as a template for Mach 30 projects (and others) moving forward.
- Jeremy - wants to have a gold standard to share with others and to use ourselves; especially useful as a stepping stone toward having project templates
- Aaron - Can also preload “prompting questions” in the template pages to help guide the use of the templates; very important to help makers working in their garages
- Jeremy - Questions to answer as we review each page in the wiki
- Is the format what we want?
- Does the information conveyed in each step’s wiki doc match what we intended?
- J - agree with the move to TOCs
- Jeremy - some of the questions (like question 5) pre-date the idea that different scales/classes of test stands would have different names (Shepard, Grissom, Glenn, etc) instead of just being later versions; this has been updated in the v1.1 docs
- Chris - so then lessons learned from larger test stands can be back ported to Shepard as later versions (2.1, 2.2, etc)
- Aaron - is there a way to capture lessons learned in our documentation (standardized place)
- J - that is a good question, there was a post mortem meeting and so there are minutes to that effect, but no formal place to put those lessons yet
- Aaron - so wouldn’t that be part of the SEP?
- J - agree, there should be a document at the end of the SEP to capture lessons learned
- Jeremy - Should the Initial Questions have identifiers much like the Requirements doc does? Maybe “STSQ1.0”?
- J - The current way of doing requirements is more of a hack. This needs to be included in an ODE module. But for this level of work, recommend we stay as lightweight as possible
- Chris - the “New File” link at the bottom should be more clearly delineated from the content
- J/Jeremy - couldn’t agree more, getting a new theme for ODE is on the roadmap
- Jeremy - has removed the “gelled” tags in the text in favor of the new wiki versioning technique
- Jeremy - took out several requirements, and scaled others back for v1.1 to accommodate scale of the project
- J - that all works for me, would like to see a v2.0 requirements review before we start development of 2.0
- Jeremy - should be able to revert back to the 1.0 requirements for 2.0 and then start scaling them back a little.
- Chris - instead of monitoring temperature over time, might it be better to show peak temperature?
- Jeremy - implementation actually does both
- J - but it is important to note the requirements do not mention capturing peak values one way or another
- Aaron - great use of the glossary
- Chris - should add a comment in the introduction section to explain the sections of the requirements (technical, project, future) and how the numbering relates back to the Initial Questions
- Jaye - alternative to breaking up the requirements by section is to add a modifier to the label (T = technical, P = project, etc).
- For example “STSRT” would be a technical requirement, whereas “STSRP” would be a project requirement.
- J - yup, all of this goes back to we need a Requirements module
- Chris - and that could then easily report out by type in a variety of ways (sorted, filtered, etc)
- J - Alternatively, we could rearrange the order of the Initial Questions by requirement section so that there are no breaks in the order of the requirements numbering
- J - happy with the way this is
- Chris - it would be very nice if the block diagram could be drawn with ODE features (possibly its own module)
- Jeremy - if you could tie the block elements back to other parts of the design (like requirements) that would be cool
- Chris - that could be done
- J - but we will have to be careful that we don’t have only one way to do systems engineering so we don’t get in the middle of Systems Engineering holy wars
- Aaron - the image can bleed into the nav bar
- Jeremy - this is a known issue and the ODE dev team is looking at fixing it.
- Chris - in many of the places, the text mentions the version of the project (version 1 of the rail system) and other pages have not done that; should add project version to top of wiki pages, increment with new tags
- ACTION - Jeremy to add version numbers at the top of the wiki pages.
- Jeremy - The original preliminary design included pricing information. Thinks this should have been left for the budget section.
- J - agree
- ACTION - Jeremy to remove budget information from Shepard 1.1 preliminary design.
- ACTION - Jeremy to reverse the order of the SEP and Documentation in the nav bar.
- ACTION - Jeremy to combine overview pages and then link the nav bar to the main wiki landing page. Make it “Home”.
- ACTION - Jeremy to move “Versions” link to the top of the nav bar with overview.
- ACTION - Jeremy to move budget, timeline, and meeting minutes into the SEP section.
- J - There’s a module to track licensing.
- ACTION - Jeremy to remove licensing link in nav bar.
- Jeremy - What exactly are the bounds of the preliminary design section? Thinking that it would just be a text description of the components, with part numbers, and how they connect and interact with each other. Basically the way it is now without the pricing info.
- J - yes
- Greg - just need to remember to include some pricing info
- J - the real lesson here is to use enough pricing detail to make good engineering decisions about the preliminary design
- Chris - general format comment, placeholders and items of documents/design that are incomplete need to be called out strongly
- Jeremy - not sure what to do specifically
- Chris - not sure what to do about that other than to be sure to document what format you choose
- Greg - what about using red text?
- J - no color for text in the wiki, but we should have a feature request for a wiki markup that means “TODO”
- ACTION - Jeremy/J put together the needed information to file this feature request.
- Chris - likes the first picture in the component overview
- Aaron - does not see a whole lot he would change
- J - there is some running together of fonts and spacing, this is more of the site wide visual facelift that needs to happen
- Aaron - would like to have seen a review of requirements with respect to the elements of the design (part A satisfies requirement 1.1)
- J/Greg - also in play is the scale of the project being so small
- Chris - the stuff one needs to know is available through the links; but should look at applying ideas above in v1.1
- Aaron - seems like the meaning of this page is unclear, need to work that out
- ACTION - Everyone to review this page during 1.1 development, and work on concretely defining what this page is for.
- Greg - the use of the term “manufacture” on this page relates to creating components (such as the Motor Mount Bracket)
- Greg - so could add some detail about manufacturing components (high level component assembly instructions)
- J/Aaron - could just break out the Manufacturing part into a separate page
- Aaron - should reconcile the budget in this page (where are we over/under, and are we still on budget).
- ACTION - Jeremy to break out Procurement and Manufacture page in the nav bar. Point Manufacture page to Assembly Instructions.
- Jeremy - What is the relationship between the Assembly step in the SEP and the Assembly Instructions in the documentation. It seems like they would just be duplicates of each other.
- Greg - in his senior design project the Assembly SEP step covered the whys behind the hows
- Greg - It’s the big picture things:
- Attaching aluminum to fiberglass.
- What tools will you need?
- What facilities have what you need to build the system.
- Greg - Assembly SEP step would hold which parts of the system are built at which hackerspaces, shipping needs, etc.
- Aaron - Keeping track of shipping can help you determine if there was a failure due to shipping damage and if the next part(s) will be fine.
- J - in general I would say the SEP documents (like the Assembly page) document our process (how did we go about arranging for time/space/etc to do assembly? what did we learn about the design during the assembly?) and the documentation pages are about how to build and use the result of the project (assembly instructions - step by step build guide, operating instructions - how do you make it do what it does, etc); also makes me think the budget and timeline should move up to the SEP section...
- TODO: Start here at the next Hangout.
- Budget
- Timeline
- BOM
- Schematics and PCB Files
- Software Source Code
- Assembly Instructions
- Operating Manual
- Safety Procedures
- Software/Firmware Summary
- Meeting Minutes
- Licensing and Attribution
- Errata
- Jeremy - Do we want to discuss how the development model that Aaron is using right now on the EPS project seems to be the way to go?
- Start a step of the SEP in the forums for discussion.
- Move the final product from the forum to the wiki, or make the changes from the forums in the already posted wiki docs.
- J. - As an additional point of procedure, we should probably be doing a documentation review before tagging a version in the wiki and in the source code repository