Workflows

1. Overview

2. Workflows

2.1. Items

2.1.1. Simple Items

When an item has no task-related state associated with it, it is considered a non-task or simple item.

Simple items imply that there's no action directly associated with this item, but it may contain child items which are tasks with action.

  1. Note
  2. Link
  3. Code

    There is a dedicated CODE keyword available for headings dedicated to a specific piece of code.

    All CC code is kept under version control and intended to be linked directly using the vc link type. Code can be linked anywhere - including org documents, other code, or online. In org documents, vc links are often used as the value of the LOCATION property.

2.1.2. Simple Tasks

Tasks are most often found as headings with some additional metadata such as scheduling info, priority, clock info, and special properties.

Tasks are always stateful and exist somewhere in one of the following abstract todo states:

TODO
Incomplete task
WIP
Work In Progress task
DONE
Completed task

Tasks are easily identified by a keyword which represents the current state. Tasks always follow a sequence with at least one 'TODO' state and one 'DONE' state. There is always an implied 'WIP' state in the sequence which come after the TODO keywords and before the DONE keywords.

2.1.3. Project Items

Projects are denoted by the special keyword PROJECT and act as containers of related work to be done. They may contain the same metadata as tasks, and may be 'downgraded' to or 'upgrade' from tasks.

Projects often contain additional metadata, such as CATEGORY and VERSION properties.

2.2. Inbox

The inbox is a flat list of items usually found in the org-inbox-file (default is ~/org/inbox.org). Items are captured by various means and then refiled to another location.

As of [2024-08-24 Sat] we capture items manually and in a local-only fashion. In the future this may change to support automatic capturing via org-protocol and email as well as peer-aware/group inboxing.

2.3. Scrum

We apply a scrum-like framework to plan our projects and tasks.

We borrow the same terminology where possible but do not align with any specific implementation. Here are some noteworthy implementation details:

  • We utilize the EFFORT property with time values as the basis of estimation such as 1d, 24:00 or 24h as opposed to story points. We measure progress in time too, but we don't represent it as such. We effectively represent it as some form of 'story point' like a percentage. This is because the estimates don't reflect realtime and shouldn't be intertwined with measures of performance.
  • Realtime values can be found in the scheduling and clock metadata as well as some timestamps like the CREATED property.
    • Performance-related metrics may be derived from the clock metadata, but I have always found it tedious to clock work time in Org mode. As of [2024-08-24 Sat] this is still unresolved, but we have some ideas to improve the workflow and implement some automatic clocking.
  • Products and Projects are separate entities. As a rule, any task belonging to a product is unable to block a project.

2.3.1. Roadmaps

The roadmap is a high-level document which describes the strategic plan associated with pre-determined period of time called program increments or PIs. The current length of a PI is 1 year.

2.3.2. Projects

For every major project in our portfolio there is a dedicated list of tasks. This list can contain any type of heading at any level but will usually consist of top-level project items containing sets of tasks to be completed.

2.3.3. Products

Products are an implementation of the value our projects provide. They represent a tangible end-goal, an anchor point for connecting with potential users and supporters, and collecting feedback.

2.4. Notes

Notes should be collected frequently and referenced often. They can be as simple as a link to a Wikipedia page, or contain a complex tree of inter-connected nodes.

2.4.1. User Notes

How you store your own notes is a very personal decision, and so I think it's important to leave a space for users to store their own notes and make their own decisions on how to use them.

As of [2024-08-24 Sat] there is no API for this at all - in the future we will likely provide an API and default implementation specifically for user notes.

2.4.2. Graphs

Graphs are a set of inter-connected nodes inspired by Roam and Zettelkasten (see org-roam).

As of [2024-08-24 Sat] this has not been implemented, but we intend to implement a fully connected knowledge graph. See graph.el.

2.5. Documentation

2.5.1. README

For every project under version control there is a readme.org file in the root directory. This file contains some dynamic blocks of basic information followed by additional content introducing the project.

2.5.2. REF

API References are generated for some of our projects based on the source code. In general these documents are generated automatically and highly structured.

2.5.3. MAN

User Manuals serve as the subject of the phrase 'RTFM'. These are always written manually and revised regularly to stay accurate.

2.6. Report

2.7. Archive

When an item is archived, it is moved to a file under version-control in the archive project.