1.1--- a/workflows.org Sun Aug 18 22:16:12 2024 -0400
1.2+++ b/workflows.org Sun Aug 25 00:15:40 2024 -0400
1.3@@ -1,61 +1,197 @@
1.4-#+title: meta/workflows
1.5+#+title: Workflows
1.6 #+author: Richard Westhaver
1.7 #+email: ellis@rwest.io
1.8-#+description: Meta Workflows
1.9+#+description: High-level description of CC workflows
1.10 #+setupfile: ../clean.theme
1.11-#+glossary_sources: glossary.org
1.12-* Roadmap
1.13+* Overview
1.14+:PROPERTIES:
1.15+:ID: ad4a24f8-7de4-479b-bc5a-7065e4b43087
1.16+:END:
1.17+* Workflows
1.18 :PROPERTIES:
1.19-:ID: be90c808-6c3b-4381-a032-af07d54f5907
1.20+:ID: 51b210fd-0ba1-41c1-a4ec-85c3d9295c02
1.21+:END:
1.22+** Items
1.23+:PROPERTIES:
1.24+:ID: 249ae0a5-0ef8-4d8a-be61-f408fb2b2cff
1.25+:END:
1.26+*** Simple Items
1.27+:PROPERTIES:
1.28+:ID: b7f9c275-90fd-407f-aa39-615fa6ab64d6
1.29 :END:
1.30-The [[https://compiler.company/plan/roadmap.html][roadmap]] is a high-level document which describes the strategic
1.31-plan associated with some pre-determined period of time, such as a
1.32-year, month, or quarter.
1.33+When an item has no task-related state associated with it, it is
1.34+considered a /non-task/ or /simple item/.
1.35
1.36-* Archive
1.37+Simple items imply that there's no action directly associated with
1.38+this item, but it may contain child items which are tasks with action.
1.39+**** Note
1.40+:PROPERTIES:
1.41+:ID: a7c60105-171a-4960-b2fc-3a8611ce210b
1.42+:END:
1.43+
1.44+**** Link
1.45 :PROPERTIES:
1.46-:ID: ca0dcc07-0517-4d04-86f0-905537cb7801
1.47+:ID: daf2c376-1969-48f9-bdbd-1a5f066e8109
1.48+:END:
1.49+**** Code
1.50+:PROPERTIES:
1.51+:ID: 81da5e76-2619-42c3-8a2a-dea2b815b261
1.52 :END:
1.53-When an item is archived, it is moved to a file under version-control
1.54-in the [[vc:comp/archive][archive]] project.
1.55-* Task Management
1.56+There is a dedicated =CODE= keyword available for headings
1.57+dedicated to a specific piece of code.
1.58+
1.59+All CC code is kept under version control and intended to be linked
1.60+directly using the =vc= link type. Code can be linked anywhere -
1.61+including org documents, other code, or online. In org documents, =vc=
1.62+links are often used as the value of the =LOCATION= property.
1.63+*** Simple Tasks
1.64 :PROPERTIES:
1.65 :ID: 66333c80-aa6f-43d7-a305-44e218dde045
1.66 :END:
1.67 Tasks are most often found as headings with some additional metadata
1.68 such as scheduling info, priority, clock info, and special properties.
1.69
1.70-Task keywords are always part of a sequence with at least one =TODO=
1.71-state and one =DONE= state.
1.72-* Project Management
1.73+Tasks are always *stateful* and exist somewhere in one of the
1.74+following abstract /todo states/:
1.75+
1.76+- TODO :: Incomplete task
1.77+- WIP :: Work In Progress task
1.78+- DONE :: Completed task
1.79+
1.80+Tasks are easily identified by a [[id:2cadda9a-22a3-4b42-ad4e-d7a774f74cba][keyword]] which represents the current
1.81+state. Tasks always follow a sequence with at least one 'TODO' state
1.82+and one 'DONE' state. There is always an implied 'WIP' state in the
1.83+sequence which come after the TODO keywords and before the DONE
1.84+keywords.
1.85+
1.86+*** Project Items
1.87 :PROPERTIES:
1.88 :ID: 560f4094-e077-4389-9e09-dba1e0d4004e
1.89 :END:
1.90 Projects are denoted by the special keyword =PROJECT= and act as
1.91-formal units of organization.
1.92+containers of related work to be done. They may contain the same
1.93+metadata as tasks, and may be 'downgraded' to or 'upgrade' from tasks.
1.94
1.95-* Code Management
1.96+Projects often contain additional metadata, such as =CATEGORY= and
1.97+=VERSION= properties.
1.98+** Inbox
1.99 :PROPERTIES:
1.100-:ID: 81da5e76-2619-42c3-8a2a-dea2b815b261
1.101+:ID: 1b426ef7-b88b-4b66-8413-df37d8312dcd
1.102+:LOCATION: [[vc:comp/core/-/blob/branch/default/emacs/lib/inbox.el][inbox.el]]
1.103 :END:
1.104+The inbox is a flat list of [[id:249ae0a5-0ef8-4d8a-be61-f408fb2b2cff][items]] usually found in the
1.105+=org-inbox-file= (default is ~/org/inbox.org). Items are [[https://orgmode.org/manual/Capture.html][captured]] by
1.106+various means and then [[https://orgmode.org/manual/Refile-and-Copy.html][refiled]] to another location.
1.107
1.108-* Data Management
1.109+As of [2024-08-24 Sat] we capture items manually and in a local-only
1.110+fashion. In the future this may change to support automatic capturing
1.111+via org-protocol and email as well as peer-aware/group inboxing.
1.112+** Scrum
1.113 :PROPERTIES:
1.114-:ID: e5c4702e-581d-41b7-a484-76730435f056
1.115+:ID: 44e6ff33-ad62-4ef0-a188-506f837648d8
1.116+:LOCATION: [[vc:comp/core/-/blob/branch/default/emacs/lib/scrum.el][scrum.el]]
1.117 :END:
1.118-** Tables
1.119+We apply a [[https://www.scrum.org/resources/what-scrum-module][scrum]]-like framework to plan our projects and tasks.
1.120+
1.121+We borrow the same terminology where possible but do not align with
1.122+any specific implementation. Here are some noteworthy implementation
1.123+details:
1.124+- We utilize the =EFFORT= property with time values as the basis of
1.125+ estimation such as =1d=, =24:00= or =24h= as opposed to [[https://www.scrum.org/forum/scrum-forum/33290/age-old-question-story-points-vs-hours][story
1.126+ points]]. We measure progress in time too, but we don't /represent it/
1.127+ as such. We effectively represent it as some form of 'story point'
1.128+ like a percentage. This is because the estimates don't reflect
1.129+ realtime and shouldn't be intertwined with measures of performance.
1.130+- Realtime values can be found in the scheduling and clock metadata as
1.131+ well as some timestamps like the =CREATED= property.
1.132+ - Performance-related metrics may be derived from the clock
1.133+ metadata, but I have always found it tedious to [[https://orgmode.org/manual/Clocking-Work-Time.html][clock work time]] in
1.134+ Org mode. As of [2024-08-24 Sat] this is still unresolved, but we
1.135+ have some ideas to improve the workflow and implement some
1.136+ automatic clocking.
1.137+- Products and Projects are separate entities. As a rule, any task
1.138+ belonging to a product is unable to block a project.
1.139+*** Roadmap
1.140 :PROPERTIES:
1.141-:ID: 8433beaf-59de-4b13-a066-8d3e636066a1
1.142+:ID: be90c808-6c3b-4381-a032-af07d54f5907
1.143+:END:
1.144+The [[https://compiler.company/plan/roadmap.html][roadmap]] is a high-level document which describes the strategic
1.145+plan associated with pre-determined period of time called program
1.146+increments or PIs. The current length of a PI is 1 year.
1.147+*** Projects
1.148+:PROPERTIES:
1.149+:ID: b94e643b-479c-400b-9679-0eb843a782fa
1.150 :END:
1.151-* Knowledge Management
1.152+For every major project in our portfolio there is a dedicated list of
1.153+tasks. This list can contain any type of heading at any level but will
1.154+usually consist of top-level project items containing sets of
1.155+tasks to be completed.
1.156+*** Products
1.157 :PROPERTIES:
1.158-:ID: ad28e021-657d-4073-b541-336df389c9fb
1.159+:ID: 5576df8c-7cc3-4d7b-a5df-9201c278a08a
1.160 :END:
1.161+Products are an implementation of the value our projects provide. They
1.162+represent a tangible end-goal, an anchor point for connecting with
1.163+potential users and supporters, and collecting feedback.
1.164 ** Notes
1.165 :PROPERTIES:
1.166 :ID: 6ebed997-12c0-4a20-88ef-df8cf424b198
1.167 :END:
1.168+Notes should be collected frequently and referenced often. They can be
1.169+as simple as a link to a Wikipedia page, or contain a complex tree of
1.170+inter-connected nodes.
1.171+
1.172+*** User Notes
1.173+:PROPERTIES:
1.174+:ID: 33ac913a-1697-49d6-8d80-542b5a1f83ec
1.175+:END:
1.176+How you store your own notes is a very personal decision, and so I
1.177+think it's important to leave a space for users to store their own
1.178+notes and make their own decisions on how to use them.
1.179+
1.180+As of [2024-08-24 Sat] there is no API for this at all - in the future
1.181+we will likely provide an API and default implementation specifically
1.182+for user notes.
1.183+*** Graphs
1.184+:PROPERTIES:
1.185+:ID: 92d71908-dba3-41b7-a126-0c6415b54579
1.186+:END:
1.187+Graphs are a set of inter-connected nodes inspired by Roam and
1.188+Zettelkasten (see [[https://github.com/org-roam/org-roam][org-roam]]).
1.189+
1.190+As of [2024-08-24 Sat] this has not been implemented, but we intend to
1.191+implement a fully connected knowledge graph. See [[vc:comp/core/-/blob/branch/default/emacs/lib/graph.el][graph.el]].
1.192 ** Documentation
1.193 :PROPERTIES:
1.194 :ID: 03e13d7e-6cda-46d4-830f-5671518bd32f
1.195 :END:
1.196+*** README
1.197+:PROPERTIES:
1.198+:ID: 111db7b0-61e0-4be3-8ec7-1a68913997ff
1.199+:END:
1.200+For every project under version control there is a =readme.org= file
1.201+in the root directory. This file contains some dynamic blocks of basic
1.202+information followed by additional content introducing the project.
1.203+*** REF
1.204+:PROPERTIES:
1.205+:ID: 26532798-89ca-4d15-aabe-e57122dea07d
1.206+:END:
1.207+API References are generated for some of our projects based on the
1.208+source code. In general these documents are generated automatically
1.209+and highly structured.
1.210+*** MAN
1.211+:PROPERTIES:
1.212+:ID: 4a299f6e-b176-43bd-88fc-3cbdde1cc2d6
1.213+:END:
1.214+User Manuals serve as the subject of the phrase 'RTFM'. These are
1.215+always written manually and revised regularly to stay accurate.
1.216+** Report
1.217+:PROPERTIES:
1.218+:ID: 307ba3e8-ef19-48da-a3c9-f5a46d6819e9
1.219+:END:
1.220+** Archive
1.221+:PROPERTIES:
1.222+:ID: ca0dcc07-0517-4d04-86f0-905537cb7801
1.223+:END:
1.224+When an item is archived, it is moved to a file under version-control
1.225+in the [[vc:comp/archive][archive]] project.
