Basic GTD Support Proposal

[dmurph]

Hello! I noticed that the roadmap and documentation mentioned GTD support goals, and I think I have a pretty good proposal here about how to do it in (I hope) the simplest way. Please take a look and let me know what you think! I can change & updated it based on feedback. This could also be moved to a separate github explainer repo, or google doc. Let me know if I should do that :)

Edit 2/20/2022: I think I prefer one of the alternates (if there is one) to make they 'typing' based on a new property called gtd, maybe. This would help conflict with other stuff and keep it simpler. I guess we could allow the user to change that property name too if they wanted to use this with other stuff?

GTD Support Proposal

Background

The GTD method is well known and has been around for a long time. It has a few core philosophies, and one of them is it's workflow.

Objective

The purpose of this proposal is to give foam the minimum required functionality to support the GTD workflow.

Goals:

• Support basic project management used by the GTD method. Specifically:
  • Active projects
  • Deferring projects
  • Incubated projects
  • Periodic reviewing
• Be as simple as possible.

Non-goals:

• Individual todo-management.
  • There is a lot of support for this already.
  • This is ironically (IMO) the least important part of GTD.
  • It might be good to support something here eventually but that can be a later iteration.

Critical user journeys

1. Create a project note (or mark existing note as a project)
2. Defer a project until X date or indefinitely
3. Incubate a project
4. List current projects (not deferred or incubated)
5. List deferred projects
6. List incubated projects
7. Mark a project as reviewed.
8. Set review time period for project (review every 7 days? every month?)
9. List all projects in need of review.

Design

The design centers around note properties. This is nice because:

• Portability - properties stays with the notes, and can easily be parsed and used elsewhere.
• Visibility - Visible to the user which reduces confusion.
• Edit-ability - They are editable by the user if they want to do their own tooling here.

Cons:

• Edit-ability - Users can put an incorrect date format, or specify both the incubated & deferred tags.

Data storage in note properties.

project note type

To signify that a note is a project / outcome, the type would be project. All notes considered by this GTD system must have this tag.

The project name is the title of the note.

Example:

---
type: project
---
# Add 2x6 raised bed to garden
...

deferred tag and DeferUntil property

To add deferred project support:

• The tag deferred is used to signify a project that is deferred.
• The new note property DeferUntil specifies the date after which the project should be considered no longer deferred.

A project is considered deferred if either of the following are true:

• It has a deferred tag.
• It has a DeferUntil property with a date after the current date.

Example:

---
type: project
tags: deferred
DeferUntil: 2021/01/01
---
# Add 2x6 raised bed to garden

[ ] Buy materials listed below from hardware store.
...

incubated tag

If a project has the incubated tag, it is considered incubated.

Example:

---
type: project
tags: incubated
---
# More educational material for Chromium developers
...

ReviewedOn and ReviewPeriod properties

To support reviewing projects on regular time periods:

• The ReviewedOn property specifies a date the project was last reviewed.
• The ReviewPeriod property is optional and specifies the number of days between reviews.
  • The default is 7 (once a week).

UX: Project tracking - Active, Deferred, Incubated

There can be a new "project tracking" view that lists projects in the active, deferred, and incubated categories. These would be 3 columns, and because these categories are be exclusive of one another it allows the user to drag & drop projects between them.

Active projects satisfy one or more of the following conditions:

• Has the project type without the tags deferred or incubated.
• Has the project type without the incubated tag, and the DeferUntil date is before the current date.

Deferred projects satisfy ALL of the following conditions:

• It has the project type.
• It has a deferred tag.
• It doesn't have an incubated tag.
• It has a DeferUntil property with a date after the current date.

Incubated projects satisfy ALL of the following conditions:

• It has the project type.
• It has an incubated tag.

Changing project states

The user can do one of the following to change the state of a project between active, deferred, and incubated:

• Drag the project between the 3 columns in the new project tracking view.
• Foam extension commands for the active editor of a project note:
  • "Activate project" ("Make project active?")
  • "Defer project"
  • "Defer project until..."
  • second menu to specify date. Even better if I can specify things like:
    • 7d
    • monday
  • "Incubate project"
• Manually edit project tags.
• (Stretch) Right-click menu from project tracking view list items
  • "Defer", "Incubate", "Activate"/"Make Project Active"

On any action here other than the manual editing, Foam would open the project file and edit the note properties to apply the status change.

Listening for project status changes

With this view open, it should update if projects have status changes. This should be relatively easy if the status change comes from the extension itself (all methods above except "manual".

However, if the user manually edits a project note, the view should listen for file saves of "project" files. It can then scan them to update the project status.

UX: Project Reviewing

There can be a "Project Reviewing" view that list projects that are due for review.

Reviewable projects satisfy ALL of the following conditions:

• It has the project type.
• It doesn't have ReviewedOn property.
• It has the ReviewedOn date, and the current date is after the ReviewedOn date plus the days specified by ReviewPeriod (which defaults to 7 days if not specified).

Marking project as reviewed

To mark the project as reviewed, the user can:

• Right click the list item from the "Project Reviewing" view
  • "Mark as reviewed"
• Foam extension commands for the active editor of a project note:
  • "Mark as reviewed"
• User manually edits the file properties

On any action here other than the manual editing, Foam would open the project file and edit/set the ReviewedOn property to the current date.

Listening for project review changes

Similar to above, the user can manually change the property here, so the extension should listen for file saves of project files and scan their properties to update the project reviewing view.

Alternatives

Listing projects: One view per project list type

Instead of having one view for all list types (active, deferred, incubated), there can be 3 views here. This might be a bit cumbersome though and fill up the tab bar. It also makes dragging between them harder.

Foam edits files with DeferUntil in the past to no longer have the deferred tag

This requires note editing by the foam extension, which adds more edge cases that could go wrong:

• The user has the file already open with edits.
• Performance hit from file writing operations on startup.
• If the date happens while vscode is open, there has to be a way to register & listen for this change, which might not be obvious.

deferred and incubated are values of new property

Because these are both tags, it means that the user can actually add both to a project. To make this harder to "mess up", this could be a separate new property, like "ProjectStatus".

Maintaining a separate database for deferred, incubated, and reviewing metadata.

An arguably simpler approach that avoids user confusion & file metadata would be to have the Foam extension just maintain the deferring, incubating, and reviewing properties itself in a database.

Pros:

• Harder for the user to mess up
• Less metadata at the top of a file

Cons:

• Less portable - cannot take information easily to another tool
• Less visible to user for scripting / understandability
• More complexity for Foam extension

Implement as separate extension

There isn't a lot here that makes this necessarily required to be part of the Foam extension. Existing work done by the foam extension certainly helps here though (having a graph of notes with properties), and there doesn't seem to be a big reason to NOT do this in this extension either. Especially if there is a goal already to have GTD support.

[chrisUsick]

Hi, this is a really well thought out approach. I want to share a perspective on the “implement as separate extension” idea. Foam currently strikes an impressive balance of simple, generic tooling that people can apply to their own organizational style/practice. For foam to maintain this balance I think support for specific organization styles should only be done through generic tooling and recipes. For example, note properties and tags, the graph and the back link panel are all generic tools that foam provides and can be leveraged to get you pretty far in any style. The documentation has already paved the way for documenting specific approaches or ways to use foam.

The second reason for investing in developing as a separate extension is it would allow lowering the barrier for future extensions. For example, I am apply PARA to my foam instance and would like to make some summary views like you described above. Clear documentation and a polished public API would make these types of extensions pretty easy. Also, I have seen people asking about programmatic access of the graph that foam builds, this could be exposed by making part of the foam api public.

All in all, I think polishing the path for making co-extensions and investing in core functionality of foam provides good long term usability and extensibility. It really depends on the direction the core team wants regarding GTD support.

[dmurph]

Looking again at the proposal, there is quite a lot that is very specific to GTD, and I can see the benefit of having this as a different extension and keeping foam more general. Especially because GTD isn't going to match everybody's work style. But if foam wanted to support this natively, this method doesn't seem too hard, and it doesn't really effect much of the other parts of foam. If you aren't using it, it wouldn't affect you.

Programatic graph access would be nice. I am interested in trying to develop this on my own but I'm very very inexperienced with vscode extension development, so I'm not confident that I would have the time to finish anything here :/

[riccardoferretti]

Thanks @dmurph for the thorough spec, and @chrisUsick for sharing your thoughts. I also use a combination of PARA and GTD, so some of the points above strongly resonate.

Indeed the goal for Foam is to provide the building blocks, accessible via an API, so that other extension builders can focus on more vertical features.

I agree that this is better implemented as a foam-gtd extension. I am very keen to have someone use the Foam API to build another extension on top of Foam, so if someone is interested in taking this on, this can be an interesting case study and I would be happy to collaborate on the API to support the extension's needs.

[chrisUsick]

As a complete n00b to vscode extension authoring, I haven’t even figured out where the integration point is within the foam code base. Does foam currently export an API that another extension can consume? I have a fairly simple use case where I’d like to implement some type of “graph aware” search where you can do fuzzy search within notes that are N degrees separated from the current note. Also, exclude notes within N degrees of another set of notes. All that to say, I’d be keen on developing some documentation around writing extensions that interact with foam to make that easier.

On Wed, Dec 29, 2021 at 4:29 PM Riccardo @.***> wrote:

Thanks @dmurph https://github.com/dmurph for the thorough spec, and @chrisUsick https://github.com/chrisUsick for sharing your thoughts. I also use a combination of PARA and GTD, so some of the points above strongly resonate.

Indeed the goal for Foam is to provide the building blocks, accessible via an API, so that other extension builders can focus on more vertical features.

I agree that this is better implemented as a foam-gtd extension. I am very keen to have someone use the Foam API to build another extension on top of Foam, so if someone is interested in taking this on, this can be an interesting case study and I would be happy to collaborate on the API to support the extension's needs.

— Reply to this email directly, view it on GitHub https://github.com/foambubble/foam/issues/894#issuecomment-1002798775, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABSIXNJ46C3MYBMDA2D43SLUTODVHANCNFSM5K5BY6UA . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

You are receiving this because you were mentioned.Message ID: @.***>

[riccardoferretti]

Foam does not yet expose an API, but the plan is to do so soon. The reason for that is that we don't want backwards compatibility issues while we fine tune the API itself. Locally it is easy to get Foam, by returning the foamPromise object in the activation function, see https://code.visualstudio.com/api/references/vscode-api#extensions

[chrisUsick]

Ah, i get that. Right, if I get time to experiment I will try that and provide any feedback regarding the api that I can. I don’t have a timeline to work on this unfortunately!

On Sun, Jan 9, 2022 at 2:11 PM Riccardo @.***> wrote:

Foam does not yet expose an API, but the plan is to do so soon. The reason for that is that we don't want backwards compatibility issues while we fine tune the API itself. Locally it is easy to get Foam, by returning the foamPromise object in the activation function, see https://code.visualstudio.com/api/references/vscode-api#extensions

— Reply to this email directly, view it on GitHub https://github.com/foambubble/foam/issues/894#issuecomment-1008365816, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABSIXNMMMXWAS37YVXPF6MTUVHTV7ANCNFSM5K5BY6UA . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

You are receiving this because you were mentioned.Message ID: @.***>

[dmurph]

Poking around, I only see the function extendMarkdownIt on the exports of vscode.extensions.getExtension("foam.foam-vscode")

Is there another place I should be looking for the foamPromise function / member?

[riccardoferretti]

This is the right place. But currently the Foam API (the foam object) is not exported. To do so (for your interim development) you can add the foam object to the exports. In the next release we might export Foam to make that easier though.