|
|
| (2 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| | | | |
| − | ==Stemnode.org== | + | ==Getting Started== |
| − | Stemnode.org consists of systems of systems maps.
| |
| | | | |
| − | ===Elements of a System Map=== | + | === Setting up an Account === |
| − | There are three elements to every system map
| + | Editing requires a user account and login. Use your real first name and surname(s), including spaces, as your username. This ensures that when you edit a review, your name shows up correctly. For example use "John Doe" instead of "johndoe" because you want your name to show up as "John Doe" in the list of authors of a manual. |
| | | | |
| − | '''1. Nodes - circles and squares'''
| + | === Starting a New Manual === |
| − | Nodes represent systems that can have subsystems or connect to other systems. Circular nodes represent a system that converts input flows into output flows while a square node represents a storage system where inputs are typically the same as outputs. For example, in a diagram of a car's electrical system an an alternator would be represented with a circle node because it converts mechanical torque into electrical energy, while the car battery would be represented with a square node because it stores energy but has electricity as both an input and output. The use of a square node vs. a circle node in a system diagram is a judgement call because sometimes a system element both stores and converts something; think of which function is more dominant when choosing how to represent the system.
| + | At the upper right of the page you can for the piece of equipment or method you are looking for. For equipment search "[Model] - [Manufacturer]". If the equipment page does not exist then you will see the option to "Create" the page above the search results. Click the "Create - [Model]-[Manufacturer]" option (It important that you search by "[Model]-[Manufacturer]" so that the pages are titled according to that standard). You will be taken to a page to edit the source code. In a separate tab, go open the [[Outline for Lab Equipment Manual]] (or [[Outline for a Method]] if appropriate) , click "View Source" and copy and paste the source code into the new page you are creating. This provides tables and an outline structure to get started, as well as ensures that you are credited as an author on the manual. Clicking "Create" at the top of the page then takes you from the source code to a visual editor that is much more similar to a word processor. |
| | | | |
| − | '''2. Ports - small circles on the edges of nodes'''
| + | == Guidelines for Writing Equipment Manuals and Methods == |
| − | Ports represent the entry point of a flow into a node. Typically, ports are named the same as corresponding flows. Ports are required to connect flows to nodes.
| + | Please use the predefined [[Outline for Lab Equipment Manual]] [[Outline for a Method|or]] |
| | + | [[Outline for a Method]] when making a new page. The easiest way is to copy and paste the source code. |
| | | | |
| − | '''3. Flows - solid and dotted arrows'''
| + | More detail is better. Many sources give equipment troubleshooting in brief, or methods in brief, but this may lead to problems and confusion. We encourage writing methods in procedural form (SOPs) to with numbered steps. It is OK if these steps may not be repeated identically in all labs; the detail will help others adapt methods and save them time.' |
| − | Flows represent the movement of something in or out of a node; solid arrows represent the flow of something physical while dashed arrows represent the flow of information. For example, the flow of gas out of a gas tank would be represented by a solid line, however the signal to the driver of the level of the gas tank would be represented by dotted line because the signal is primarily of an informational value (despite an actual physical process sending that signal).
| |
| | | | |
| − | ===Guidelines for Building System Maps=== | + | == Advanced Editing == |
| − | '''Do's and Don'ts'''
| + | Mediawiki help pages are available for navigating software features. Most users will prefer to use the visual editor which is similar to using a word processor, however [https://www.mediawiki.org/wiki/Help:Formatting basic formatting code] is helpful for advanced users. |
| − | -Do build generalized system maps that fit a generalized purpose, but do not attempt to represent every potential configuration of that system in a single diagram. Instead place each practical configuration in a separate node so that others can use that configuration in other systems.
| |
| | | | |
| − | -Do map specific systems; maps of systems that actually exist at a specific location (even if that location may move in time). These often serve as case studies that others can learn from.
| + | '''Adding Youtubes;''' Videos can be added using the source code below. The "video ID" corresponds with what comes after the equals sign in the URL of the video. For example [https://www.youtube.com/watch?v=I2aFnPihzao www.youtube.com/watch?v=I2aFnPihzao] is embeded with the code <nowiki><youtube>I2aFnPihzao</youtube></nowiki>. |
| − | | + | <nowiki><youtube> Video ID </youtube></nowiki> |
| − | -Do build system maps of theoretical systems that could be possible in the future but are not yet built, as long as they serve a function or improvement for society.
| |
| − | | |
| − | -Do use a node to hold nodes that are all the same type of system, or components in the same category of systems (e.g. Building Scale Wastewater Treatment Systems, Electrical Components), however do not try to connect nodes with flows because you often end up with messy diagrams where many combinations of subsystems are possible.
| |
| − | | |
| − | -It is typically appropriate to name ports the same as the external flow that connects to it. When two or more different flows connect to it use more generic terminology which describes all the connecting flows succinctly (e.g. if both starch and sucrose are input flows to a port, then "carbohydrates" may be an appropriate name for the port). Alternatively, use terminology for the connection point itself (e.g. a "terminal" on a battery, or a "Universal Serial Bus (USB)" port on a computing system).
| |
| − | | |
| − | -Do not title flows with verbs or actions. Names of flows should typically be nouns although adjectives may also be appropriate to include.
| |
| − | | |
| − | ==Wiki.stemnode.org==
| |
| − | | |
| − | Wiki.stemnode.org is a separate site, with a separate login from stemnode.org, that is based on mediawiki software. Mediawiki help pages are available for navigating software features. Most users will prefer to use the visual editor which is similar to using a word processor, however [https://www.mediawiki.org/wiki/Help:Formatting basic formatting code] is helpful for advanced users. This manual covers specifically how the mediawiki software is used for stemnode.
| |
| − | | |
| − | ===Getting Started Editing=== | |
| − | '''Setting up an Account''' - Editing requires a user account and login. This login is separate from your stemnode.org login. Use your real first name and surname(s), including spaces, as your username. This ensures that when you edit a review, your name shows up correctly. For example use "John Doe" instead of "johndoe" because you want your name to show up as "John Doe" in the list of authors of a manual.
| |
| − | | |
| − | '''Do's'''- Use the predefined outlines when making a new manual on an object in a system. Copy and paste the source code from the appropriate outline to start;<br/>
| |
| − | [[Outline for a Technological Process Node]] (for circular nodes)<br/>
| |
| − | [[Outline for a Natural Process Node]] (for circular nodes)<br/>
| |
| − | [[Outline for a Storage Node]] (for square nodes)<br/>
| |
| − | [[Outline for a Flow]] (for both informational and physical flows)<br/>
| |
| − | All can be changed to use terminology which fits the specific process or flow, however the general format should be adhered to in order to keep a consistent layout of information for all nodes and flows.
| |
| − | | |
| − | ===Guidelines for Writing Reviews===
| |
| − | -Write at the level appropriate to the associated node(s). Content associated with subsystem nodes should not be duplicated at the parent level node, although brief summaries of the subsystems are typically appropriate. The interaction of two nodes within a system should be covered at the parent level node. Also, makes and models of subsystems should be specified at the parent level node while how the subsystems works should be specified in the relevant subsystem wiki.
| |
| − | | |
| − | -Often times reviews should have longer and more detailed titles than the nodes which they link from. This is because the system diagrams have context that imply many things wheras the reviews are out of context and a single review can be linked to multiple nodes. When a succinct name for a process does not exist you should lead the title with it's primary output (e.g. "Yogurt production" has a primary output of "Yogurt"). When a product can be made from different inputs, use the format "[Primary Output] from [Primary Input]" in the name of the review.
| |
| − | | |
| − | -Ensure the reviews can remain relevant to the node(s) they are associated with by keeping content generalized only to the level of that node. The interaction of two nodes needs to be written about at the review associated with the parent level node.
| |
| − | | |
| − | -Give yourself and other authors credit by including <code><nowiki>{{Template:CiteAuthors}}</nowiki></code> as the top line in the source code of each review.
| |
Getting Started
Setting up an Account
Editing requires a user account and login. Use your real first name and surname(s), including spaces, as your username. This ensures that when you edit a review, your name shows up correctly. For example use "John Doe" instead of "johndoe" because you want your name to show up as "John Doe" in the list of authors of a manual.
Starting a New Manual
At the upper right of the page you can for the piece of equipment or method you are looking for. For equipment search "[Model] - [Manufacturer]". If the equipment page does not exist then you will see the option to "Create" the page above the search results. Click the "Create - [Model]-[Manufacturer]" option (It important that you search by "[Model]-[Manufacturer]" so that the pages are titled according to that standard). You will be taken to a page to edit the source code. In a separate tab, go open the Outline for Lab Equipment Manual (or Outline for a Method if appropriate) , click "View Source" and copy and paste the source code into the new page you are creating. This provides tables and an outline structure to get started, as well as ensures that you are credited as an author on the manual. Clicking "Create" at the top of the page then takes you from the source code to a visual editor that is much more similar to a word processor.
Guidelines for Writing Equipment Manuals and Methods
Please use the predefined Outline for Lab Equipment Manual or
Outline for a Method when making a new page. The easiest way is to copy and paste the source code.
More detail is better. Many sources give equipment troubleshooting in brief, or methods in brief, but this may lead to problems and confusion. We encourage writing methods in procedural form (SOPs) to with numbered steps. It is OK if these steps may not be repeated identically in all labs; the detail will help others adapt methods and save them time.'
Advanced Editing
Mediawiki help pages are available for navigating software features. Most users will prefer to use the visual editor which is similar to using a word processor, however basic formatting code is helpful for advanced users.
Adding Youtubes; Videos can be added using the source code below. The "video ID" corresponds with what comes after the equals sign in the URL of the video. For example www.youtube.com/watch?v=I2aFnPihzao is embeded with the code <youtube>I2aFnPihzao</youtube>.
<youtube> Video ID </youtube>
