Connexions
Open source documentation and publishing platform
Notes
Connexions provides modules and collections. Modules need to be stand-alone concepts; collections need to be a sequence of modules.
The Distributed Collaboration structure starts with Definitions, which are then combined into Projects, which are then embellished and published as Reports.
Maybe create a module for each self-evident definition, no matter how small. Connexions doesn't include any way to manage a project, so that has to happen outside of their service. As the Definition modules are created, they get combined into a project file. That project file then becomes its own module (or set of modules?). Finally, additional modules would be created for things like Overview, and Introduction, and BOM. After all that is done a collection would bring everything together to define one machine.
Instructions
How To Tag/Name Modules
- Date of last edit
- Instruction language
- Key words in levels of specificity
- A word/phrase that clearly distinguishes the type of machine (tractor) TYPE
- A word/phrase that clearly distinguishes the previous level from all other things with the same type name (LifeTrac) NAME
- A word/phrase that clearly distinguishes the previous level from all other things with the same model name (Version 4) VERSION
- That tells us how to distinguish the machine it belongs to from all other machines, now we need to know how to distinguish the part from all the other parts of that machine. Maybe define it based on what the part itself is and leave the subsystem definition for the project stage. That way if someone wants to use a bearing (or whatever) they don't have to worry about calling by the subsystem name of a different machine.
- Actually, maybe it would be better to leave the machine definition for later and instead just define the part by the attributes it has in isolation. Start most specific, first, then build up to least specific last.
Connexions allows a title and keywords. It makes sense to keep the title short, and add bulk to the keywords. Also, the title should be the part that is least likely to change, hence the most specific name possible.
Machine: Structure (keeps parts of the machine from moving in relation to each other) Mount (holds something in place, but is primarily intended to be a reconfigurable interface rather than part of the structure) Mechanism (allows parts of the machine to move in a controlled way in relation to each other) Actuator (controls the movement of the machine's mechanisms) Hardware (a small piece of the machine that doesn't fit into any other category)
KISS
These are all prototypes. The way they're named will most likely change no matter how good it is right now. So, just define a simple way to lend some consistency and self-evidentness to the information for right now. The names don't need to be self-evident in an objective sense, just in terms of the GVCS project itself. The only people even working with them will be dedicated developers. We can worry about 8-th grade level communication when we write the report.
So, the title should be: Something very specific within the context of the machine itself.
The keywords should be: Anything else that seems relevant, whether more or less specific.
We'll take advantage of the fact that GVCS machines are designed to be as simple as possible. Even if there is some small amount of confusion in naming convention that simplicity will make the confusion easy to resolve. As long as the confusion isn't a show-stopper within the instructions for the one specific machine it will be fine.
