Documenting Instances

Documenting Instances

Each time a resource is used in a project we call that an "instance" of that resource. Artemis provides a framework to document instances and the way they fit into your project. These instances and their relationships to other instances are then mapped automatically on the instance network so you can visualize your team's work.

Step One: Create Instance

To add a new instance to your archive press the green "New Instance" button. A modal like the one below will appear where you can do four things:

  1. Name your instance.
  2. Choose the instance's underlying resource. You need to designate what this is an instance of — do this by pasting in the resource's ID number.
  3. Indicating the instance's status. This will be highly dependent on your company's workflows. You can add status tags like "test," "production," "in progress," and more. You can also create custom tags as needed.
  4. Add an overview, a few words to describe what the instance does at a glance.

Step Two: Document Instance

After you create and name your instance you can document it. This is when you'll record exactly how and why you've deployed a resource using the modal below that will appear automatically. There are nine tabs you can use, The first three contain general information. The next four are to record instance-specific documentation. The eighth tab pertains to the network, and the final one is settings.


In order of appearance, here's what each tab does:

1) Overview Tab

This tab displays general information about the instance.

2) Resource Details Tab

This tab displays information about the instance's underlying resource. This is exactly the same information found on this resource's catalog entry.

3) Resource Content Tab

Information on this tab identifies the underlying resource's location. This is exactly the same information found on this resource's catalog entry.

4) Input Datasets

This is the first of the tabs you can use to document your instance. Use this tab to identify any databases the instance relies on. For example, if you're documenting a script that processes data from a database you should press the green "Add Dataset" button and use the modal that appears to search for the relevant instance of that database.

5) Output Artifacts

This is where you can document the outputs of your instance. For example if you're making an instance of a script that generates a dataset you should note the relevant instance of that dataset as an artifact.

6) Origin

If your instance was generated by an instance of a different resource, you should denote that point of origin here.

7) Deployments

If the instance you're documenting is used by another in some way not otherwise acknowledged by another field, record that relationship here.

8) Network

Clicking this button will show the instance you're working with on its relevant network.

9) Comments

This is where you can read and leave comments about the instance in question. Any user with access to the archive can add comments — you do not need to be approved as an editor.

10) History

Artemis automatically logs every action that affects the instance in question. Every time it's edited, moved, etc. will be recorded here.

11) Settings

This is where you can change permissions for who is allowed to edit the instance you're documenting.