# What is Acorn? {% hint style="danger" %} This Acorn knowledge base is in its early stages of development and will be progressively adapted and updated. {% endhint %} Acorn is an open-source, peer-to-peer project management application. It is designed and built as a scrum-alternative, [Agile Development Pattern](https://en.wikipedia.org/wiki/Agile_software_development) for distributed software development teams. Acorn functions through defining [Intended Outcomes](/about-acorn/the-ontology-of-acorn#outcomes) for a project in a [Dependency Tree](/about-acorn/the-ontology-of-acorn#dependency-tree) structure. Acorn is built as a [Holochain](https://holochain.org) application, meaning it runs on decentralized peer-to-peer computing and can be used without server infrastructure or a hosting service. The users of a particular Acorn instance are its hosting power. ## FAQ ### What license is Acorn under? Why? Acorn is under the [Cryptographic Autonomy License v1.0](https://github.com/holochain/cryptographic-autonomy-license) (CAL), [approved by the Open Source Initiative (OSI)](https://opensource.org/licenses/CAL-1.0). CAL was created for the Holochain project to protect both source code and user data from restriction. It frees an end user from having their data held from them by a party that develops or hosts software licensed under CAL. ### Who developed it? Acorn was envisioned and prototyped (using a third party platform) by the [Holochain](https://holochain.org) core development team in 2018 to organize their own planning and execution process. In August 2019 [Sprillow](https://sprillow.com) undertook a design process and began building Acorn on Holochain and continues to today. In June 2022 the first major release of Acorn (Alpha) was published and it's currently in an Alpha testing phase. [Lightningrod Labs](https://lightningrodlabs.org) is the container for the continuous development of Acorn alongside some other projects powered by Holochain. Please consult our [AUTHORS.md file](https://github.com/lightningrodlabs/acorn/blob/main/AUTHORS.md) for a list of contributors and their organizations. ### What are future plans for Acorn? Acorn is being developed and improved on a regular basis, and is currently is in **Alpha** testing phase. ## Contributing We welcome contributions from anyone to the Acorn project. Here are some ways that you can contribute. ### Log an issue If you download Acorn, and use the software, you might occasionally run into some problems. If and when you do, those issues can be brought up with the Acorn development team, by logging an issue here in the Github repository for the project. If you have a Github account, or create one, you can do that here: When filing an issue, please include a detailed description of the following: * which operating system you were using * a list of steps you took that led to the issue ("steps to reproduce") * a screenshot (if not sensitive information) ### Start a discussion We do not have a separate 'chat' forum for Acorn, apart from the Discussions space on the Github project. Please use it to bring up questions, or to explore potentials. It can also be a good space to connect with other Acorn users, and hear about how they're using Acorn. ### Contribute directly to the software, as a developer If you are interested to contribute to Acorn's development, welcome! Acorn is written in languages such as Rust and Typescript, and frameworks such as Holochain, and React. If you have proficiency in either Typescript and React for writing frontend code, or Rust for writing backend code, or both, then you may find it intuitive to contribute. Generally, new features come through a design -> development pipeline defined by the workflows of the [Sprillow](https://sprillow.com) team, but these workflows could be adapted to more 'open' workflows if the right opportunity presented itself. Otherwise, contributions may remain more-so in the space of bug fixes and other technical-first features, such as algorithms or scripts. It should be noted that while the Rust code has unit tests, the frontend code does not. That is another area for potential improvement (front end testing). In terms of getting the codebase up and running on your local development machine, check out [DEVELOPERS.md](https://github.com/lightningrodlabs/acorn/blob/main/DEVELOPERS.md). In terms of getting more familiar with the codebase, you can get a rather in-depth introduction by watching these two videos: * Acorn technical deep dive, Part 1: * Acorn technical deep dive, Part 2: While some of that code may be out of date, the general introduction should still apply, and be helpful. In terms of getting more deeply involved, talking with other contributors, just start by reaching out to to explore what makes sense! # The Ontology of Acorn The concept of Acorn as a peer-to-peer agile project management ## Outcomes In the Acorn ontology projects are managed through the lens of Intended Outcomes, their [dependencies](#dependency-tree), [Scope](#outcome-scope) and [Achievement Status](#achievement-status) in a [Plan-Do-Check-Act Cycle](#plan-do-check-act-cycles) process. Instead of a title, an Outcome is defined through an **Outcome Statement**, demonstrating a desired state in the project in declarative. For example: > Acorn no longer uses a legacy unmaintained library and instead it is replaced with a modern typescript API definitions. {% hint style="warning" %} An Outcome is different from a goal: Outcomes are the measurement and evaluation of an activity’s results against their intended or projected results. Outcomes are what you hope to **achieve** when you accomplish the goal. {% endhint %} ## Dependency Tree Also known as the “**State-of-Affairs**” tree, a **Dependency Tree** (in mathematics known as Directed Acyclic Graph or DAG) is a tree-form representation of the dependencies between **Intended Outcomes** related to a project. Outcomes in a tree structure can have **Parents**, **Children**, or both. The [**Achievement**](#achievement-status) of a **Parent Outcome** is dependent on the achievement of its [**Children**](/project-views/map-view/outcome-connections) **Outcomes**. ![An example of a Dependency Tree structure representation in Acorn, seen in Map View of a project](/files/HH4R31RtvCWklb4Ew1PP) ## Outcome Scope In the Acorn ontology, [**Scope**](/outcomes/outcome-scope) is the most important and required property of the **Intended Outcomes** in a project. A Scope shows the complexity state of an Outcome, which implies certainty (or lack of it) around the amount of work, steps, and the amount of time required to have that Outcome achieved. There are three broad Scope categories in Acorn: ### Uncertain Scope An Outcome which we don’t know or are the still in the process to determine its amount of work, steps, and the amount of time required to achieve. An Uncertain Scope without Children can be switched to Small Scope. ### Small Scope An Outcome that we are certain can be achieved within a short amount of [time](/outcomes/time#time-for-small-scope-outcomes) (agreed between team members beforehand, for example 1 day). An Outcome that is Small in Scope doesn't have Children, but can have a [Tasklist](/outcomes/tasklist). Small Scoped Outcomes are signified with **Leaf symbol** on Map View and Table View. ### Big Scope An outcome that is **Certain but not Small** in Scope. A Big Scope for an Outcome is always Computed, and only has Small and/or Big Scope Children. If an Outcome only has Small and/or Big Scope Children it automatically shifts from Uncertain to Big in Scope. ## Achievement Status Every Outcome has an [**Achievement Status**](/outcomes/achievement-status) property in Acorn. It can either be **Achieved**, **Not Achieved**, or **Partially Achieved**. By default, an Outcome is **Not Achieved** when it is created. The Achievement Status of an Outcome is either **Adjustable** or **Computed**, depending on its **Scope** and **Children**. ## Plan-Do-Check-Act Cycles Acorn creates an Agile process based on the [Deming Plan/Do/Check/Act cycle](https://en.wikipedia.org/wiki/PDCA), that is less bound to some of the traditional dependencies of Scrum and more applicable to projects and organizing beyond software development. The patterns Acorn enables and the resultant State-of-Affairs trees are scalable, handle complexity and uncertainty, and work with distributed groups. # Who is Acorn for Anyone who is involved in project management could use Acorn. However, Acorn is particularly designed to help with project management of distributed software development teams. # Best Practices Learn tips on how to manage your project in Acorn. {% hint style="info" %} This page is under development. {% endhint %} ## Getting started with your project in Acorn ### Starting with the highest level intended Outcomes Acorn focuses on desired and intended [Outcomes](/about-acorn/the-ontology-of-acorn#outcomes) instead of goals. What it means for you and your team is that when you start a project in Acorn you would want to start with writing down the highest level Outcome or Outcomes for your project in **declarative** sentence (we call this an [Outcome Statement](/outcomes/outcome-statement)). For example, one of the highest level Outcomes that we want to achieve for the Acorn software project would be: > Software dev teams have a seamless and frictionless experience doing project management using Acorn.

An example of a highest level Intended Outcome, viewed in Expanded View

### Breaking down the Outcomes At first any intended Outcome is **Uncertain** in [Scope](/about-acorn/the-ontology-of-acorn#outcome-scope): It's not clear how long it is going to take, how it could be achieved, or who should work on it for it to get achieved. So you would need to break down your highest level Outcome(s) into smaller scoped Outcomes. You would need to ask yourself: * What Outcomes do we need to achieve first to consider the highest level Outcome achieved? * What's our Hypothesis for breaking down the Outcome in a specific way? You will then need to add [Children Outcomes](/project-views/map-view/outcome-connections) to the Outcome you are breaking down. That's where the dependency relationship between Outcomes comes into play, modelled as a [**Dependency Tree**](/about-acorn/the-ontology-of-acorn#dependency-tree) of Outcomes in Acorn (visible in [Map View](/project-views/map-view)). This Breakdown process might take you or your team some time. This allocation of time and focus is accounted for in Acorn. When you are in the process of breaking down an Uncertain scope Outcome mark it as **In Breakdown** mode. You can also give it a [**Breakdown Time Estimate**](/outcomes/time#time-for-uncertain-scope-outcomes) for how long it could take you to break down that Outcome into Small Scoped Outcomes (shown as the Children and/or [Descendants](/project-views/map-view/outcome-connections) of that Outcome). You can also define who is doing this Breakdown by [assigning](/outcomes/assignees) them to that Outcome.

Breaking down the Outcomes in the Dependency Tree to reach to the level of Small Scope Outcomes. If an Outcome only has Small and/or Big Scope Children it automatically shifts from Uncertain to Big in Scope.

### Creating a Dependency Tree of Outcomes Keep breaking down each Outcome till you can confirm the lowest [Child Outcome](/project-views/map-view/outcome-connections) in each branch is clear in Scope and can be achieved within a short amount of time (right now this is automatically set as 1 day in Acorn). These Outcomes are [**Small in Scope**](/about-acorn/the-ontology-of-acorn#small-scope), and you can mark them as such by opening the [Expanded View](/project-views/expanded-view) of that Outcome and switching the Scope to Small.

An example of a Dependency Tree of a project seen in Map View. The Outcome on the top is the highest level Outcome.

An example of a Small Scope Outcome, viewed in Expanded View

### Modifying the Dependency Tree Acorn is meant to be an agile project management methodology. It means that as you progress through developing your project, your Dependency Tree would evolve or change. Acorn is designed to accommodate these iterations. For example, at some point you might realize you have a different highest level Outcome for your project, and you can modify your Dependency Tree of Outcomes accordingly. [Learn how to add or change the connections between Outcomes](/project-views/map-view/outcome-connections). ## Your team's day-to-day workflow Now that you've broken down your tree in Map View and it has grown large enough with some Small Scoped Outcomes available, you may begin to think about where to start. Here are some tips: ### Picking and ranking project priorities The team member or members in project management hat would **mark** certain Outcomes in the Dependency Tree as [High Priority](/outcomes/high-priority-outcomes). Then they have to **sort** between those High Priority Outcomes in [Priority View](/project-views/high-priority-view) to rank them. If an Outcome marked as High Priority is: * **Uncertain Scope with Children** * It needs to be broken down until all of its lowest level [Descendants](/project-views/map-view/outcome-connections) are Small in Scope. * **Uncertain Scope without Children** * The priority for it is[ breaking down](#breaking-down-the-outcomes) that Outcome. * Make sure there is relevant team member (or members) [assigned](/outcomes/assignees) to breaking down the Outcome. * **Small Scope:** * It needs to be [assigned](/outcomes/assignees) to related team member or members * Have a [Tasklist](/outcomes/tasklist) created for it. * You can also add a [Target Date](/outcomes/time#time-for-small-scope-outcomes). ### Achieving Small Scope Outcomes The team members in 'doer' hat (those who execute to achieve Small Scope Outcomes) will be able to access the Outcomes assigned to them via the [Table View](/project-views/table-view) and using the filter '**Only show my cards**'. They can also view the High Priority Outcomes in [Priority View](/project-views/high-priority-view) and see which ones they are assigned to. {% hint style="info" %} In the future we are intending to have the '**Only show my cards**' filter for the Table View as well. {% endhint %} #### Going through the Tasklist If the Small Outcome already has [Tasklist](/outcomes/tasklist) added to it by the members in Project Management hat then the Assignee can go through those tasks and check them off as they complete each task. The Assignee also can create a Tasklist for themselves to help them break down the steps to Acheive that Small Scope Outcome. Checking off each task in the Tasklist updates the [Progress Indicator](/outcomes/progress-indicator) for that Outcome. When all of the tasks are checked off the Outcome automatically turns into **Achieved** Status. If for any reason it is determined that the Outcome is not achieved yet, you can manually switch the [Achievement Status](/outcomes/achievement-status) back to **Not Achieved**.

An example of the Tasklist for a Small Scope Outcome, viewed in Expanded View

{% hint style="success" %} If you achieve all the Small Scope Outcomes that are Children and/ore Descendants of a Big Scope Outcome, then the Parent Outcome automatically becomes Achieved. {% endhint %} ### Connecting Outcomes with Your GitHub Repository Acorn is designed with project management for distributed software teams in mind. There is a GitHub Issue or Pull Request link option that you can add to any Outcome. This will help you and your team cross reference between your GitHub repo and your Acorn space. #### Translating a GitHub Issue to an Outcome What could be very useful for project management of a software product is translating GitHub issues into Outcomes in Acorn. This will help you make a cohesive understanding of where the external feedback belongs in the bigger picture of your project's Dependency Tree. For example, we received the issue below on GitHub:

An example of an Issue on a the GitHub repo for the project

Then, we translate it into an intended or desired Outcome and [link the GitHub Issue](/outcomes/github-link) to it:

An example of a GitHub Issue translated into an Outcome on Acorn

Then we look into whether this Outcome speaks to a bigger Outcome we want to achieve for our project. For example, this Outcome helps us with achieving a bigger scoped Outcome: > App functions normally and without interruption in terms of connectivity. So we make the recently created Outcome a [Child](/project-views/map-view/outcome-connections) of the bigger scope Outcome:

An example of the newly created Outcome becoming a Child of a bigger scope Outcome

# Updating the App Automated and manual flows for updating Acorn ## Automatic Updates The Acorn app will automatically update if the Holochain versions remain compatible, which should be indicated by the minor release number remaining the same. ## Manual Updates When a new Minor or Major release comes out, you will currently have to manually migrate project data from an older version. To update the app to the new version while keeping your projects' data, you would need to do the following: 1. *Before* you install a new version of the app, go to the Project View and click and [export the project](/projects/export-a-project) in JSON format. Do this for every project's data you wanting to keep. 2. Download and Install the latest version of the app for your device from [the Acorn website](https://acorn.software/#download) 3. Run the newly installed app. 4. Depending on the release, and whether it has had 'breaking changes', you may be required to re-create a new profile. 5. Import the data for each project by clicking on [**Import a Project**](/projects/import-a-project) button on the Dashboard page. 6. For the shared projects, [Invite Members](/projects/invite-members-to-a-project) again. {% hint style="warning" %} **Only one person per shared project** should take responsibility for migrating that project to the new version in manual update process. Other project members should be notified, and invited to the migrated project. Note the coordination this requires. {% endhint %} ## Updates and Personal Projects You do not have to update to the newest release in order to access any of your personal projects on Acorn. However, it's always recommended to update to the latest version to benefit from improved experience. # Project Members Project Members are displayed via their **avatars** throughout that Project. You are able to see a Project Member's name by hovering over their avatar. You can [Invite others to a Project](/projects/invite-members-to-a-project) to become a Member that Project. {% hint style="warning" %} Currently you **won't be able to remove any existing Members** from a Project you are a member of. Any other existing Project Members are also able to invite others to that Project. {% endhint %} ### Project Member Status There are three types of Status for a Project Member: #### Self Assigned Status Displayed as colored dots on the corner of Project Member avatars. Any Project Member can assign themselves a Status to appear wither **Online** (green), **Away** (yellow), or **Offline** (grey) to the other Project Members. The default self-assigned Status is Online (green). To change your Self-Assigned Status at any time, click on your avatar on top right corner of the screen and select **Change Status** option from the menu to see the Status option and click the one you want. ![Changing your Self-Assigned Status](/files/IYjs74xto2d2CFEF4pwg) #### Connectivity Status A Project Member is either **Connected** or **Disconnected** from the Project at any given moment. This connectivity Status depends on whether the Project Member has the app open and active (with connected Websocket), and that if they are connected to the Internet. The Connectivity Status is automatically detected by the app. If a Project Member is Disconnected, their avatar will display at a lower opacity level. #### Public Key Association Status (Ghost Members) At the moment when you migrate your Project data to [a newer version of the app](/about-acorn/updating-the-app) (which currently needs to be done manually), the Project Members previously assigned to any Outcomes of that project will be **Ghosted**. That means **their metadata is dissociated from their Public Key** which identifies them as a real person. A Ghost Project Member avatar is displayed as at a lower opacity with hatch pattern on the Outcomes they where assigned to. Ghost members are now claimable after updating the app to a new version. The app will automatically associate your Public Key with your ghost member profile upon launching the new version of the app. {% hint style="info" %} You can remove any unclaimed Ghost Members that are on the [Assignees Lists](/outcomes/assignees) of an Outcome. However you won't be able to add a Ghost Member back as an Assignee. {% endhint %} {% hint style="info" %} In the future there will be a more automated app updating process which will prevent the users from having to migrate their project data manually and having to inviting back each member to that project. This automation will also prevent most of the cases that cause the Ghosted Member situation. {% endhint %} # Projects Dashboard Projects Dashboard is your default "homepage" for Acorn app and shows an overview of all the projects you are a member of. In addition to an overview of your existing projects, in the Projects Dahsboard you can [Create a Project](/projects/create-a-project), [Join a Project](/projects/join-a-project), [Import a Project](/projects/import-a-project), and [Invite Members to a Project](/projects/invite-members-to-a-project). To navigate back to your Projects Dashboard from a specific Project View, click on the Acorn logo on top left side of the screen. # Create a Project In the Projects Dashboard, click on Create a Project button and follow the instructions. # Join a Project In the Projects Dashboard, click on Join a Project button and Paste the 5-word secret you received from the project host. When you are joining a project, ***at least one***** existing peer** from that project needs to be online in order for you to sync to that project. If everyone is offline, the project will be added to the project queues until you and at least one peer are online so that the project can sync. Once you both are online the project may continue to **take one or more minutes** to synchronize and to display itself as available in your dashboard. {% hint style="warning" %} In order to be able to collaborate on a project, you and the other project users must be on the same "major version" of Acorn. This means that the first number in the Acorn version code, such as the "5" in "5.0.1-alpha", must be the same. E.g. Version 6.x.y WON'T synchronize with someone using Acorn version 5.x.y. {% endhint %}

After you enter the 5-word secret to join a project, Acorn will look for any online peers for that project and until it has found at least one to sync with, it will indicate that the project is waiting to sync.

# Import a Project In the Projects Dashboard, click on Import a Project button and follow the instructions. {% hint style="warning" %} You can only import projects in **JSON** format. Any project files exported **prior** to Acorn version 1.0.1-alpha are not importable in app versions 1.0.1-alpha and beyond. {% endhint %} # Invite Members to a Project Do one of the following to invite members to a specific project: * **In My Projects Dashboard,** * click on the "plus" (+) icon attached to the list of member avatars for that project, and follow the instructions. * OR click on the Project Settings icon (three dots) to open the Project Settings and then Click on Invite Members button. * **In Project View,** on top left header, * next to the list of member avatars, click on the "plus" (+) icon. * OR click on Project Settings icon to open the Project Settings and then Click on Invite Members button. {% hint style="warning" %} Currently you **won't be able to remove any existing Members** from a Project you are a member of. Any other existing Project Members are also able to invite others to that Project. {% endhint %} # Export a Project While viewing a specific project, click on the Export icon on top left header. Select **JSON (importable)** or **CSV** format to export. {% hint style="info" %} Make sure to export your projects' data in **JSON** format before [updating the app](/about-acorn/updating-the-app) to a new version. {% endhint %} # Delete or Leave a Project If your project is shared, you have have the option to remove yourself from that project (you can't delete it for everyone since it's a peer-to-peer application!), and if your project is personal and not shared, you have the option to delete the project. 1. Open the Project Settings by either: 1. Clicking on the Three Dots icon for the project in Projects Dashboard, or 2. Clicking on the Settings icon on top left header if inside of the project view 2. click on Remove Self from Project button (if it's a shared project) or Delete Project button (if it's a personal project). # Map View Map View is the most useful view for **team members in Project Management/Product Ownership hat** as the Map View gives an overview of the project status as a whole. ### Switching Between Project Views You can switch between different project views (Map View, [Table View](/project-views/table-view) and [High Priority View](/project-views/high-priority-view)) by clicking on their associated icon in the top left header when inside a project. ![Map View, Table View and High Priority View icons on project header. You can switch between these views by clicking on their icons.](/files/FloGaw0I1RXBDN7RDEbo) # Creating Outcomes To create a new Outcome card in Map View, do one of the following: * **Creating a stand-alone Outcome** 1. Double click on an empty space on the canvas 2. Write down an Outcome Statement. 3. Hit Enter or click away on the canvas to finish creating the Outcome. * **Creating a connected Outcome** 1. Hover over an existing Outcome card on the canvas. 2. Two purple connection points appear at the top and the bottom of the Outcome card. 3. If wanting to create a **Child Outcome**, click and drag from the bottom purple point and release. 4. If the Outcome card does not does have a Parent, you can create a new **Parent Outcome** by clicking and dragging from the top purple point and release. 5. Write down an Outcome Statement. 6. Hit Enter or click away on the canvas to finish creating the Outcome. ### Scope of a New Outcome When creating a new Outcome, the Scope of that outcome is **Unknown** by default when it is created, and in Expanded View you can change the Outcome's Scope. you can check the **Small Scope checkbox** when creating the Outcome to make that Outcome small in Scope from the get-go and save time.

When creating a new Outcome, the default Scope will be Unknown, but you can check the Small Scope checkbox to make that Outcome small in Scope from the get-go.

# Removing Outcomes To remove an Outcome from the project, do one of the followings: * **In Map View** 1. **Click** on an Outcome card to select it. 2. Hit **Delete** Key. * **On the Outcome's Expanded View** 1. On right column under the Actions sections, click on **Archive** button. To remove several Outcomes at once: * In Map View, **hold Shift and Click** on the Outcome cards you want to remove. * Release Shift. A menu will appear at the bottom center of the screen. * Click on the Archive icon from the bottom menu. * Confirm that you want the selected **Outcomes** to be archived. {% hint style="warning" %} Currently the Archived Outcomes can't be accessed in the app. {% endhint %} # Outcome Connections On Map View the Outcomes and their dependency relationships are displayed and can be modified. These relationships are called **Connections** and shown as lines between each two Outcomes that are related. All Outcome Connections are **Parent-Child** relationships. **Ancestors** of an Outcome are the Parents of that Outcome's Parent. **Descendants** of an Outcome are the Children of that Outcome's Children. ## Connecting Two Outcomes in Map View 1. Hover over one of the Outcome cards you want to connect in Map View. 2. To make that Outcome a Child of another Outcome, click and drag from the purple dot above the card. 3. While still dragging your mouse/trackpad, bring the Connection line to the Outcome card you want to make Parent for the Child Outcome. 4. Snap the Connection line and release it on the purple dot below the Parent Outcome. 5. Release your mouse/trackpad to create the Connection. ### **Connecting two Outcomes far from each other in Map View** Sometimes you might need to connect two Outcome cards that are far from each other in Map View and it is inconvenient to drag your mouse/trackpad across the map to bring the Connection line to the second Outcome. In that situation you can follow the steps below: 1. Press and hold **Shift Key.** 2. Click on the two Outcomes one by one while holding Shift Key to select both of them. 3. A menu appears at the bottom of the Map View screen. Click on the **Outcome Connection icon** on the left of the menu. A popup appears. 4. Inside the popup, choose the Parent and the Child Outcome. 5. Hit Save button. {% hint style="info" %} You can use this method to make an Outcome Parent to several other Outcomes at once. To do so follow the steps above while having selected all the Outcomes involved. {% endhint %} ## Disconnecting two Outcome in Map View 1. Click on the **Connection** line between the two Outcomes. 2. Hit **Delete** key. ## Changing an Outcome Connection in Map View ### Changing the Parent of an Outcome If an Outcome has an existing Parent, the purple dot above that Outcome has the function of **re-assigning** the Parent: 1. Click and drag from the **top purple dot** it to remove the existing connection line. 2. Drag the connection line to the **bottom** of a different Outcome (to become the Parent) OR release in empty space to create a new Outcome and make that new Outcome the Parent at the same time. {% hint style="info" %} If you have done this in error, simply hit **Escape** key before releasing your mouse/trackpad to reverse your action. {% endhint %} ### Re-assigning a Child for an Outcome If you want to disconnect a Child from an Outcome and at the same time connect it to a diffrent Outcome: 1. Click and drag from the **bottom purple dot** it to remove the existing connection line. 2. Drag the connection line to the **top** of a different Outcome (to become the Child) OR release in empty space to create a new Outcome and make that new Outcome a Child at the same time. # Canvas Navigation in Map View You can select your preferred navigation mode on canvas in Map View based on your primary pointer device to optimize your interaction experience with the canvas. This navigation mode preference determines how you **Zoom** and **Pan** in Map View. ### Switching Between Navigation Modes 1. Click on **your Avatar** on top right side of the screen. 2. Click on **Preferences**. 3. Select the **Trackpad** or the **Mouse** option based on your primary pointer device. 4. Hit **Save Changes**.

Canvas navigation options in Preferences

# Tree Navigation by Keyboard You can select your preferred tree navigation mode by keyboard in Map View between two options: 1. **The most left**: When you navigate to Children or Parents by keyboard, it will navigate to the most left Outcome in that group. 2. **Show a modal**: When you navigate to children or parents by keyboard, a modal will pop up each time for you to select which Child or Parent you want to navigate to. ### Switching Between Keyboard Tree Navigation Modes 1. Click on **your Avatar** on top right side of the screen. 2. Click on **Preferences**. 3. Select the **The most left** or the **Show a modal** option based on your preference. 4. Hit **Save Changes**.

Tree navigation by keyboard options in Preferences

# Map Viewing Options In Map View you can customize your viewing options for the following: 1. **Layout Algorithm**: We have included three different options including **Classic**, **Minimum** **Height**, and **Minimum Width** to choose from. 2. **By Achievement Status**: You have the option to hide all Achieved Outcomes from view, or show them all. 3. **By Scope**: You have the option to hide all Small Scoped Outcomes from view, or show them all. To access these map viewing options, simply click on the Eye icon at the bottom left side of the Map View right next to zooming toggles.

Map Viewing Options in Map View

# Table View The Table View displays the project Outcomes and their properties (including project **ID number**, **Outcome Statement**, **Progress Indicator**, and **Assignees**) in a table format. At the top of the page, you are able to select filters to apply to the table, in order to reduce the amount of Outcomes you are seeing at once. This can be helpful particularly for finding Outcomes that you yourself are '[assigned](/outcomes/assignees) to', or limiting Outcomes to those with a certain Tag or [Tags](/outcomes/tags). Table View is most useful for **team members in 'doer' hat**. # High Priority View High Priority View displays the Outcomes that are marked as **High Priority**. In this view you can drag and drop the outcomes to sort their order of importance for you and your teammates. ## **Indented Tree View** On the left side of the High Priority View there is **Indented Tree View** from which you can search existing Outcomes and add them to the High Priority list by Click on the **Plus** (+) icon on hover (the Plus (+) icon only shows for Outcomes that are not currently set as High Priority).
# Expanded View An Expanded View of an Outcome shows you all the details and metadata related to the Outcome and let's you modify the information related to that Outcome. ### Entering the Expanded View for an Outcome * **Map View:** Double click on any Outcome or while selected on an Outcome (with blue borders) use Enter key. * **Table View:** Click on the Outcome's statement. * **Priority View:** Hover over the High Prioruty Outcome'x box and then click on the Expand Icon on top left side of the box. ### **Expanded View variations based on the Outcome's Scope** Depending on the Scope of the Outcome you find slightly different options on the right and left columns of the Expanded View. For example: * Small Scope Outcome has [Tasklist](/outcomes/tasklist) tab on the left but Big and Uncertain Scope Outcomes have [Children List ](/outcomes/children-list)tab instead. * The [Achievement Status](/outcomes/achievement-status) for Big Scope Outcome is entirely computed and can't be manually changed. * If an Outcome doesn't have children you have the option to toggle the [Scope](/outcomes/outcome-scope) between Uncertain and Small. * Only Uncertain Scope Outcome can be marked as **In Breakdown** mode.

An example of a Small Scope Outcome, viewed in Expanded View

An example of a Big Scope Outcome, viewed in Expanded View

An example of an Uncertain Scope Outcome, viewed in Expanded View

# Outcome Scope See [Outcome Scope](/about-acorn/the-ontology-of-acorn#outcome-scope) in the Ontology of Acorn page to learn more. ## Changing an Outcome's Scope {% hint style="info" %} You can only adjust the Scope of an **Outcome with no Children**. The Scope of the Outcomes with Children is automatically computed based on the scope of their Children. {% endhint %} To change an Outcomes' Scope that has no Children, do one of the following: * **In Table View** * Click on the Outcome's Statement to open the Expanded View for that Outcome. * On the right column under the Scope section switch between Small and Uncertain scope options. * **In Map View** * Double click on the Outcome card to open the Expanded View for that Outcome. * On the right column under the Scope section switch between Small and Uncertain scope options. # Outcome Statement Instead of a title, an Outcome is defined through an **Outcome Statement**, demonstrating a desired state in the project in declarative format. For example: > Acorn no longer uses a legacy unmaintained library and instead it is replaced with a modern typescript API definitions. ## Editing an Outcome's Statement To edit an Outcome's Statement, do one of the following: * **In Table View** 1. Click on the Outcome's Statement to open the Expanded View for that Outcome. 2. Click on the Statement to make edits to the Statement. Click anywhere off of the text input field to save your changes. * **In Map View** 1. Double click on the Outcome card to open the Expanded View for that Outcome. 2. Click on the Statement to make edits. Click anywhere off of the text input field to save your changes. {% hint style="info" %} When a member is editing an Outcomes' Statement, the other members will see it in Being Edited status and won't be able to edit it at the same time. {% endhint %} # Achievement Status See [Achievement Status](/about-acorn/the-ontology-of-acorn#achievement-status) in the Ontology of Acorn page to learn more. ## Changing an Outcome's Achievement Status {% hint style="info" %} You can only adjust the Achievement Status of a **Small Scoped Outcome.** The Achievement Status of non-Small Scope Outcomes is automatically computed. {% endhint %} To change a Small Scoped Outcomes' Achievement Status, do one of the following: * **In Table View** 1. Click on the Outcome's Statement to open the Expanded View for that Outcome. 2. On the right column under the Achievement Status section, click on the current Status to see and select between the options. * **In Map View** 1. Double click on the Outcome card to open the Expanded View for that Outcome. 2. On the right column under the Achievement Status section, click on the current Status to see and select between the options. # Progress Indicator Progress Indicators display the achievement progress of an Outcome at one glance. Depending on the Scope of the Outcome, they take slightly different forms. Below are the information items in Progress Indicators for each Outcome Scope category: * **Uncertain Scope** * Number of Achieved Small Scope **Descendants** (if any) * Number of Total Small Scope **Descendants** (if any) * Number of Uncertain **Descendants** (if any) ![An example of Progress Indicator for an Uncertain Scope Outcome](/files/OqnDAMBwFIzeSVzBRmc7) * **Small Scope** * Number of Achieved Tasks from the Outcome's Task List (if any) * Number of Total Tasks from the Outcome's Task List (if any) * Percentage of Achieved Tasks in relation to the total Tasks (if applicable) * Progress Circle (in Expanded View and Table View) or Progress Bar (In Map View) ![An example of Progress Indicator for a Small Scope Outcome ](/files/DMalogCfcJzLiinoxtdV) * **Big Scope (Not Small or Uncertain)** * Number of Achieved Small Scope **Descendants** (if any) * Number of Total Small Scope **Descendants** (if any) * Percentage of Achieved Small Scope **Descendants** in relation to the total Small Scope Descendants (if applicable) * Progress Circle (in Expanded View and Table View) or Progress Bar (In Map View) ![An example of Progress Indicator for a Big Scope Outcome](/files/9qTkvBRtcVbymwsgQ4ar) {% hint style="info" %} Remember that **Descendants** are inclusive of all the Children as well as Children of Children (etc.) of an Outcome. {% endhint %} # ID Number Every Outcome has a 6-digit ID Number that is **randomly and automatically** set upon creation of that Outcome. ID Number is useful for addressing and referring to a specific Outcome without the need to mention the Outcome Statement (Outcome Statement can be updated and changed at any time). The ID Number of an Outcome is displayed both on the Expanded View of that Outcome (top left side of the card) and also in Table View (left side of the Outcome Statement column). {% hint style="info" %} The ID Number of an exisitng Outcome cannot be changed. {% endhint %} # Assignees Assignees are the project members who are working towards Achievement of a specific Outcome. A member can self-assign or assign other members to an Outcome. ## Adding or Removing an Assingee for an Outcome To add or remove an Assignee for an Outcome, do one of the following: * **In Table View** 1. Click on the Outcome's Statement to open the Expanded View for that Outcome. 2. In the middle column under Assignees section, click on the Plus (+) button to see the Members list. 3. To add a member as an assignee, click on their avatar to select them. To remove an assignee from the Outcome, click on their avatar to deselect them. * **In Map View** 1. Double click on the Outcome card to open the Expanded View for that Outcome. 2. In the middle column under Assignees section, click on the Plus (+) button to see the Members list. 3. To add a member as an assignee, click on their avatar to select them. To remove an assignee from the Outcome, click on their avatar to deselect them. # Tags You can add Tags to any Outcome to categorize them and to easily filter through them in the [Table View](/project-views/table-view). Tags can have a custom name and associated color. ## Creating a Tag or Adding a Tag to Outcome To create a Tag or Add a Tag to Outcome, do one of the following: * **In Table View** 1. Click on the Outcome's Statement to open the Expanded View for that Outcome. 2. In the middle column, click on **Add/Edit a Tag** button to open the Tags popup. 3. To create a Tag, click on **Create a Tag** button, and fill out the **Label** for the tag and choose a hex color code for the **Background Color** of the Tag. You can also choose a background color from the app's preset color swatches by clicking on the color swatch next to the Background Color field. Then click one of the swatches to select that color. 4. To add an existing Tag, click on the desired Tag from the Tags List to select. 5. To close the Tags popup click on **Add/Edit a Tag** button again. * **In Map View** 1. Double click on the Outcome card to open the Expanded View for that Outcome. 2. Follow the same instructions as described above. {% hint style="warning" %} In the current version of Acorn, created Tags are not editable or delete-able yet, but they can be added to removed from an Outcome at any time. {% endhint %} # GitHub Link You can add a GitHub Issue or Pull Request link to an Outcome for easy access and reference. ## Adding a GitHub Link to an Outcome To add a GitHub link to an Outcome, do one of the following: * **In Table View** 1. Click on the Outcome's Statement to open the Expanded View for that Outcome. 2. Click on the GitHub Link field. 3. Paste in your full GitHub issue or pull request URL. 4. Hit Enter. * **In Map View** 1. Double click on the Outcome card to open the Expanded View for that Outcome. 2. Click on the GitHub Link field. 3. Paste in your full GitHub issue or pull request URL. 4. Hit Enter. ## Changing or removing a GitHub Link from an Outcome 1. In Expanded View, hover over the existing GitHub to have the Edit Icon show up. 2. Click on the Edit Icon. 3. To Remove the link, select all of the URL, delete it, and hit Enter. To change the link, select all of the URL and paste in the new GitHub Issue or pull request link. 4. Hit Enter. # Time An Outcome can have **Time** associated with it. The nature of the Time depends on the [Scope](/outcomes/outcome-scope) of that Outcome: ### **Time for Uncertain Scope Outcomes** When an Intended Outcome is Uncertain in Scope, we don't know how long it can take to become [Achieved](/outcomes/achievement-status). We first would need to break it down into Small Scoped Outcomes so that it becomes certain in Scope and could be measured. For an Uncertain Scope Outcome we can set a **Breakdown Time Estimate** for how long it could take us to break down that Outcome into Small Scoped Outcomes (shown as the Children and/or [Descendants](/project-views/map-view/outcome-connections) of that Outcome). This could help the members in project management hat to be able to have an idea of the project's state as a whole. ### **Time for Small Scope Outcomes** There are two type of time associated with Small Scope Outcome: 1. **Small Scope Outcome Achievement Time:** This is the *maximum* amount of time that would take a Small Scope Outcome to be Achieved, prevously agreed and set by the project's team members. 2. **Target Date:** You can set an optional Target Date for a Small Scope Outcome to help you and your team keep on track. {% hint style="warning" %} Currently **Small Scope Outcome Achievement Time** in the app is preset as **1 day**. In the future versions of the app there will be the option to customize this field for each project. {% endhint %} ### **Time for Big Scope Outcomes** The Time associated with Big Scope Outcomes is defined as **Achievement Time Estimate,** is always **Computed**, and is signified with a calculator icon on the left side of the estimated time. This Achievement Time Estimate for a Big Scope Outcome is computed from the number of Small Scope Children the Outcome has, multiplied by the preset **Small Scope Outcome Achievement Time**. For example, if it is set for the project that an Small Outcome would take up to 1 day of work for it be Achieved, and a Big Scope Outcome has 14 Small Children, the Achievement Time Estimate would be 14 days. ## **Setting or Editing Time for Uncertain or Small Scope Outcomes** To set or edit Time for an Outcome, do one of the following: * **In Table View** 1. Click on the Outcome's Statement to open the Expanded View for that Outcome. 2. In the middle column under **Breakdown Time Estimate** (for Uncertain Outcomes) or **Target Date** (for Small Outcomes) section, click on the "Click to set time" or the existing time field to open the Time popup. 3. Use the calendar to pick the Start and End dates for Breakdown Time Estimate or the Date for Target Date. * **In Map View** 1. Double click on the Outcome card to open the Expanded View for that Outcome. 2. In the middle column under **Breakdown Time Estimate** (for Uncertain Outcomes) or **Target Date** (for Small Outcomes) section, click on the "Click to set time" or the existing time field to open the Time popup. 3. Use the calendar to pick the Start and End dates for Breakdown Time Estimate or the Date for Target Date. ## **Removing Time for Uncertain or Small Scope Outcomes** On Time popup click on **Clear All** button on top left of the popup to remove the existing Time for the Outcome. # Description You can add an extended Description to any Outcome. ## Adding or Editing an Outcome Description To add or edit an Outcome's Description, do one of the following: * **In Table View** 1. Click on the Outcome's Statement to open the Expanded View for that Outcome. 2. In the middle column under Description section, Click on the Description field to add or make edits to the Description. All changes to the Description are applied instantly. * **In Map View** 1. Double click on the Outcome card to open the Expanded View for that Outcome. 2. In the middle column under Description section, Click on the Description field to add or make edits to the Description. All changes to the Description are applied instantly. {% hint style="info" %} When a member is editing an Outcome's Description, the other members will see it in in Being Edited status and won't be able to edit it at the same time. {% endhint %} # High Priority Outcomes You can mark an Outcome as High Priority to give it extra attention among other Outcomes in your project. You can have more than one High Priority Outcomes at once in your project. When an Outcome is marked as High Priority it will: * gain a "glow" in the [Map View](/project-views/map-view) and is easily identifiable. * will appear in the [High Priority View](/project-views/high-priority-view). ## Marking or unmarking an Outcome as High Priority To mark or unmark an Outcome as High Priority, do one of the following: * **In Table View** 1. Click on the Outcome's Statement to open the Expanded View for that Outcome. 2. On the right column under the **Mark As** section check or uncheck the High Priority option. * **In Map View** 1. Double click on the Outcome card to open the Expanded View for that Outcome. 2. On the right column under the **Mark As** section check or uncheck the High Priority option. * **In High Priority View** 1. You can also add an Outcome to the High Priority list by using the [Indented Tree View](/project-views/high-priority-view#indented-tree-view). # Entry Point Outcomes You can mark an Outcome as being an "Entry Point" to make it a point of access in the project, which you can jump to directly from the [Projects Dashboard](/projects/projects-dashboard). You can have more than one Entry Point at once in your project. When an Outcome is marked as Entry Point it will: * appear in you Projects Dashboard under your project's Entry Points list. * in project's Map View, will appear in Entry Points list, which can be accessed by clicking on the **Entry Points Icon (Doorway)** on the top left header. ![Entry Points icon and popup on project header](/files/Ji9Kz5l1qSekMxqXAjVi) ## Marking or unmarking an Outcome as Entry Point To mark or unmark an Outcome as Entry Point, do one of the following: * **In Table View** 1. Click on the Outcome's Statement to open the Expanded View for that Outcome. 2. On the right column under the **Mark As** section check or uncheck the Entry Point option. * **In Map View** 1. Double click on the Outcome card to open the Expanded View for that Outcome. 2. On the right column under the **Mark As** section check or uncheck the Entry Point option. ![](/files/SB6wGHAX9fINFSTk6xRy) # Comments You can add Comments to any Outcome to ask questions, trade in ideas, help the assignees, and more. {% hint style="warning" %} At the moment, you would not be able to delete any existing Comments. This feature will come in a future version of the app. {% endhint %} ## Adding a Comment to an Outcome To add or edit an Outcome's Description, do one of the following: * **In Table View** 1. Click on the Outcome's Statement to open the Expanded View for that Outcome. 2. On the left column, click on the **Comments** **tab** shown as two chat bubbles icon. 3. Select the message field and type down your comment. 4. Click on the **Send Message** icon, or hit **Shift + Command/Ctrl.** * **In Map View** 1. Double click on the Outcome card to open the Expanded View for that Outcome. 2. On the left column, click on the **Comments** **tab** shown as two chat bubbles icon. 3. Select the message field and type down your comment. 4. Click on the **Send Message** icon, or hit **Shift + Command/Ctrl.** # Tasklist Only **Small Scoped Outcomes** can have a Tasklist assigned to them. Completing a Task and checking it off brings you one step closer to making that Outcome Achieved. ## Adding a Checklist Item to Tasklist To add a Checklist item in a Tasklist, do one of the following: * **In Table View** 1. Click on the Outcome's Statement to open the Expanded View for that Outcome. 2. On the left column, click on the **Tasklist** **tab** shown as two checkboxes icon. 3. Click on Add a Checklist Item field. 4. Type in the task content. 5. Hit Enter. * **In Map View** 1. Double click on the Outcome card to open the Expanded View for that Outcome. 2. On the left column, click on the **Tasklist** **tab** shown as two checkboxes icon. 3. Click on Add a Checklist Item field. 4. Type in the task content. 5. Hit Enter. {% hint style="warning" %} At the moment, existing Tasklist items are not editbale. If you need to change an exisitng checklist item, you would need to delete it and create a new one. {% endhint %} # Children List If an Outcome has Children, you would be able to see its Children as a list on **Expanded View. Click on the Children tab on the left column** and to the Outcome's Children and to navigate to a Child Outcome. In **Table View**, you would also be able to see an Outcome's Children by clicking the **Chevron** icon (next to the Outcome's Statement and [Progress Indicator](/outcomes/progress-indicator)) to expand the Children of that Outcome. # Ancestors Breadcrumbs On Expanded View there are **Breadcrumbs** for the Ancestors of the selected Outcomes on the top left corner of the screen. The Outcome Statement of the direct Parent and also the very first Ancestor is displayed. Any Ancestor in between the these two are displayed as three dots. You can navigate to the Parent or an Ancestor of the Outcome directly by clicking on it in the Breadcrumbs. ![An example for Ancestors Breadcrumbs for an Outcome on Expanded View](/files/VNUvwiJU7jsal9kxcYj6) # Clearing Application Data How to reset your application data, and perform a 'factory reset'. Warning: this is a destructive action. With Acorn, all your data lives on your device. There are a couple of reasons you may wish to delete your application data: 1. You want to delete the identity and data associated with it 2. You don't have any important data, and you want to recover the application from a faulty state that it is in If you want to 'factory reset' and delete all of your application data, **notably this includes the private key which represents your identity among your peers**, then you can easily do so. The instructions differ slightly depending on your operating system. {% hint style="info" %} Note: if you are an advanced user and are running multiple Acorn versions side-by-side, DO NOT follow these instructions as they will delete data for ALL Acorn versions. {% endhint %} Depending on your operating system, all of your Acorn application data lives in one of these folders: * `%APPDATA%\acorn` on Windows * `$XDG_CONFIG_HOME/acorn` or `~/.config/acorn` on Linux * `~/Library/Application Support/acorn` on macOS {% hint style="info" %} If you are on MacOS, it may be difficult to navigate to this folder from the Finder. If you are not comfortable with the command line, you can use the Finder application and then navigate to the application menu "Go -> Go to Folder..." and then `fill in` "`~/Library/Application Support/acorn" and press Enter.` {% endhint %} {% hint style="danger" %} To delete all your data, including your identity (keys): delete the application data folder from your system, by at least moving it to the trash. {% endhint %} Having deleted your data, the next time you start the application you will be prompted to fill in details about your profile once again, with a fresh start. # Your Project Data How to keep your project data safe while using Acorn alpha Given that we are dealing with a novel database ([Holochain](https://www.holochain.org/)) we are keen to make sure that people can use the app and that it responds reliably. In testing Acorn, we are not just testing our own software application built with Holochain, but Holochain itself, as Acorn is probably the app that is closest to “production ready” built completely on top of Holochain. We hope you are as excited as we are to see this happening. As you use Acorn, please try to do so in a careful considered way, at this early phase. We invite you to try inputting information that relates to a real project you are working on, and to use it for actual tracking of work during your day to day, but we advise against making Acorn the one and only place you enter or store that information. One way to feel secure with your data is to [**regularly click on ‘export’ and download a JSON export of your whole project**](/projects/export-a-project). This file will safely keep an up to date snapshot of your data and give you the option to re-import that data into a new project.