I struggle with scoping work in a way that allows me to capture all our thoughts and decisions in a quick and convenient way.

I have scoped work in many different ways and different formats: spreadsheets, text documents and task managers. I found they all has some kind of friction that made it unsatisfactory.

The things I want in a scoping process:

Ability to capture as much of our thoughts and decisions as possible while we are thinking about the project as a whole
- Capture a limitless amount of detail
- Group, sort and structure the items
Able to read what has been scoped, reference parts and make updates with as little friction as possible
Easily show or send the scope to all stake holders for review. Easily readable
Have a way to transfer the content of the scope into a task management system
- Machine readable structured content to allow for interoperability

With these desires I I reviewed the different method's pros (+) and cons (-).

Task managers

(+) Usually allows for large text areas to add as much information as needed
(+) Usually has a hierarchy to use to group issues
(+) Usually allows for sorting in a list or with dates
(-) Not easy to see the whole scope
(-) Details are hidden behind clicks
(-) Usually have to click a lot to update and move issues
(+) Structured data, don't need to transfer to task manager
(+) A good task manager is interoperable
(-) Not easy for those not in the system to see

Spreadsheets

(-) Large amounts of text in cells is awkward
(-) Does not handle hierarchy well
(+) Allows for manual sorting by row or automatic by column
(+) Can see each issue with all details showing
(+) Structured data in columns to easily transfer
(+) Everyone can read a spreadsheet file
(-) The way you may need to structure the data could confuse people

Text document

(+) "Unlimited" space to capture thoughts
(+) Usage of headers can help with hierarchy
(+) Manually sort issues by moving them around the document
(+) Easily see and update issues and sections
(+) You can see the scope by scrolling the document
(+) All details are visible
(-) Data not structured in a way that is machine readable
(+) Everyone can see a rich text document if using standard document format like Word
(-) I still don't like rich text document editors because they want to structure things for you

So it seems that the text document is the best except for the structured data part. This is where my solution comes in. There is a wonderful text format that has structured data in a way that maintains the human readable nature of the content: Markdown. One of the great design aspects of markdown is how little you need to add to human readable text in order for it to be machine readable. The machine doesn’t need to understand the human readable parts and the machine readable parts are logical enough for the human to also parse it. There is also a large ecosystem for rendering and displaying markdown text for non-technical people. That ecosystem also has lots of parsers available to convert the text into more machine readable structure for interoperability.

Any one can take this idea and create scope documents and developer parsers and workflows to accomplish this task. Here is the way I format my documents, I call it "Workdown".

Headers

Headers allow for the hierarchy of tasks. We will use the standard markdown header notation to denote the different levels of items. Each level has a specific meaning as described below. And the headers will be the main delimiter between tasks.

Project Name: `#`

What project this scope is being written for. I usually assume one project per markdown file.

Epics/Phases/Feature sets: `##`

Large chunks of work. Can group work by timeline milestones, by like features or anything else you want. Examples

Phase 5 - Q2 2027
Products
Set up

Stories `###`

Discreet deployable unit of code. Examples:

User can edit a product
About Page

Issues: `####`

Discreet testable unit of code Examples:

edit form saves
content block shows on product page

tasks: `#####`

Helpful break outs of larger issues. If an issue is able to be broken down further for the benefit of the person doing the work then use this. Examples:

Create table with list of fields
Set up SSO Authentication provider

When parsing and importing the headers act like a tree structure where the higher number headers (more #'s) are child items of the lower number headers above it.

Body

The body of an item is defined as the content between the headers. The content is associated to the header item immediately above it. Aside from the below format for attributes the remaining markdown syntax is used to format as normal markdown would be formatted.

Attributes

When working on scoping out a section you will want to add specific attributes, such as estimates or assignees. You can accomplish this in two ways. Markdown code blocks can group all the attributes in a single spot. Or using a standard in a popular Obsidian plugin called Dataviewto assign variables.

Code Blocks

Markdown code blocks use three back tick characters ``` to open and close the block. If you define the language after the first three backticks many renderers will parse and style the code when displaying. I use workdown as the language and write attributes in yaml formatting. This could allow a workdown parser to read and parse the attributes.

Example:

```workdown
estimate: 3h
assignee: andy.rooney@example.com
type: bugfix
```

Data values?

The Obsidian plugin Dataview defines the ability to set key-value pairs. On their own line use :: to separate the key and value. For example I could add in the body of an issue Estiamte:: 2h or assigneee:: andy.rooney@example.com,ed.asner@example.com

Example Attributes

Examples of variables I have used:

estimate: guessed hours to do the work
type: what kind of work is this task
sprint: An integer used to define which sprint this work should be in. This is a way of ordering the work chronologically without using a date
assignee: the worker assigned to the work

Conclusion

I have written scopes in this format and have enjoyed them. There is still a learning curve to give this document to others to read but it is pretty simple. I still need to build a workdown parser to make this fully interoperable. This is a step I hope to take as I use this format more.

Example

Below is an example of a workdown file

# Project Name
```workdown
PO: xxxxx@xxxxx.com
SPM: xxxxx@xxxxx.com
BE: xxxxx@xxxxx.com
FE: xxxxx@xxxxx.com
Devops: xxxxx@xxxxx.com
Job number: PROJ-xxxxx
```
The body of the project section is here for the description of the whole project. Introduce the reader to what the work is about.


## Phase 1
Start Date:: 2026-06-04
Here is the text for the description of the phase. The above attribute defines the start date of the phase


### Story Name
Heres is a particular story


#### Issue 1
```workbreakdown
estimate: 2h
type: Action
sprint: 1
assignee: BE
```
This is the contents of the task body
- any markdown syntax allow
- You can have lists


#### Issue 2
```workbreakdown
estimate: 2h
type: Style
sprint: 1
assignee: FE
```
You can even leave the body empty like below


##### task
```workbreakdown
estimate: 2h
type: Style
sprint: 1
assignee: FE
```

#### Issue 3
```workbreakdown
estimate: 2h
type: Component
sprint: 1
assignee: BE
```

### Story Name here 2
Heres is a particular story

This would render like:

Project Name

BE: xxxxx@xxxxx.com
FE: xxxxx@xxxxx.com
Job number: PROJ-xxxxx

The body of the project section is here for the description of the whole project. Introduce the reader to what the work is about.

Phase 1

Start Date:: 2026-06-04

Here is the text for the description of the phase. The above attribute defines the start date of the phase

Story Name

Heres is a particular story

Issue 1

estimate: 2h
type: Action
sprint: 1
assignee: BE

This is the contents of the task body

any markdown syntax allow
You can have lists

Issue 2

estimate: 2h
type: Style
sprint: 1
assignee: FE

You can even leave the body empty like below

task

estimate: 2h
type: Style
sprint: 1
assignee: FE

Issue 3

estimate: 2h
type: Component
sprint: 1
assignee: BE

Story Name here 2