Diagramming Basics

After creating your first Topic, you'll be greeted by the Workspace:

The Workspace is divided into a few sections:

1. the Diagram - this is where you'll break down your Topic with nodes and edges.
2. the Topic Pane - on the Details tab, you can see more details about the Topic, or about the currently-selected node or edge; on the Views tab, you can switch between ways of looking at the Diagram.
3. the Toolbar - here you'll find buttons to take different actions, like undo/redo and delete.

Nodes

At the center of your diagram, there's a purple node with a few details on it:

1. the node's text - a brief summary of the concept that the node represents.
2. the node's type - conveys what kind of concept the node represents. In this case, this node represents a Problem.
3. the node's indicators - these indicate some information; you can see what each indicator does here.

You might want to start your Topic with a solution proposal, or a question, or something else, but the default is starting with a problem. For our example, we're going to model a situation where cars are going too fast in a neighborhood, and we're worried about the safety of the neighborhood's children.

Editing a node's text

Let's start by changing the node's text to "cars going too fast in my neighborhood". Select the node by clicking on it, then the node's text will become editable.

Adding a node

After selecting the node, you'll notice some buttons appear above and below the node. These are for adding related nodes. You can hover them to see which button adds which kind of node.

When you're modeling your Topic, you can add nodes in whatever order they come to mind for you, but we're going to start by justifying why this is a problem. Detriments can help us here - they're negative effects created by the problem. Let's add a Detriment by clicking the magenta sinking house button, and edit the text to "pedestrians might get hit".

Scoring to convey opinion

One key feature in Ameliorate is that you can score nodes to convey how important you think they are. To score a node, hover over or click the circular score in the node's upper-right corner, and click on a score.

Generally, 1-4 are negative, 5 and unscored ("-") are neutral, and 6-9 are positive. Let's score the Detriment as a 9, conveying that we think it's a big detriment that pedestrians could get hit by cars.

Acknowledging small details

Something nice here is that we can acknowledge that the problem actually creates a positive effect, while clearly specifying that we think it's not as important as the negative effect. Let's add a Benefit node "people get places faster", but score it as a 2 to convey that we think it's relatively unimportant.

Justifying a node

Just as any node can be scored, any node can also be supported or critiqued. If you select the Detriment node, you'll notice the Topic Pane shows details specific to the selected node:

1. notes for the node - scratch details, or any extra context to clarify the node
2. justification - supports or critiques for the node; these can be used to justify why the node may be more important or less important
3. research - questions, facts, or sources that are relevant to the node

Let's add a Support "reduces feeling of safety in neighborhood" to the Detriment node, by clicking the blue thumbs-up button.

Chaining justification

You can also chain justification together, for example to justify why the feeling of safety is important. You can do this two different ways. The first way is to go to the details for the Support you added by clicking the Details Indicator:

then you can add your justification the same way you added the first Support. Let's add a Support "reduced safety correlates with reduced home values":

The second way is to view the justification tree for the node; let's click the Justification Tree indicator:

then we can add a node the same way we added our Benefit and Detriment nodes:

Diagramming choices

You might have noticed that sometimes justification can be represented either in an argumentative manner or as part of the Topic's structure. In this case, reduced safety is modeled as a Support, but could also be modeled as a Detriment that's created by "pedestrians might get hit".

The author's opinion is: trains of thought are easier to model as argument, but modeling through the Topic's structure makes it easier to understand how it relates to the rest of the topic. It may be best to initially model as argument, and later adjust the Topic's structure to reflect the argument.

Sometimes there are a few different ways to represent the same thing; check out the Diagramming Choices page for some thoughts on these situations and their trade-offs.

Research nodes

Oftentimes, you won't have all the information you want for your Topic, and you'll have to do some research. There are a few nodes intended for facilitating and organizing research:

• Questions: to identify information that may be useful to find out
• Answers: to directly answer a question; sometimes the answer might just be reflected through your Topic's structure
• Facts: to identify information (usually statistical) that may be relevant
• Sources: to identify places that may have relevant information

Let's return to our Topic structure by clicking the 'x' in the upper-right corner of this Justification Tree, select the Detriment node again, and take a look at the Research section:

Adding research nodes

This is where we can add research nodes. Let's click the question mark button to add a Question "are there many children, handicapped, elderly, in the area?":

Let's also add a Fact "residential street has 25 mph speed limit" to the Problem "cars going too fast in my neighborhood":

The Research Diagram

Sometimes navigating between research details can be cumbersome. The Research Diagram can help alleviate this - go to the Views tab in the Topic Pane, and click the Research Diagram button:

Now we can view all the research nodes for our Topic, along with the nodes they're relevant for. Let's add a Source "WI traffic manual" to our Fact, and put the link "https://wisconsindot.gov/dtsdManuals/traffic-ops/manuals-and-standards/teops/13-05.pdf (opens in a new tab)" in the Source's notes:

What's next?

Those are the basics of how Ameliorate works - now you can try it out on your own problems! If you have questions, feel free to ask in the Discord server (opens in a new tab).

For more advanced usage, check out the other pages in the App section of this documentation, e.g. Features or Diagramming Choices. You can also see other examples of Topics here (opens in a new tab).