-
Notifications
You must be signed in to change notification settings - Fork 18
/
gtd-1.0.0-rc1.norg
504 lines (375 loc) · 25.3 KB
/
gtd-1.0.0-rc1.norg
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
* A description of the UI implementation within Neorg's GTD
*** Most Important Design Goals
- ZERO FRICTION - user interfaces should provide as little friction as possible when capturing a note
of any kind.
- Fast response times - the interface should be very responsive and database operations should not be felt.
- Dynamic data - notes and ideas should be representable in many formats - the form of a list, a calendar, a graph.
- Ensure that migrating from "small" to "larger" thoughts is unobtrusive.
- Provide several calendar views and graphs to visualize data.
- All data should be stored in plain-text `.norg` files, such that it can easily be version controlled and sent across
devices.
- Understand the nuances and pain points of other note taking solutions (points back to the "zero friction" bullet point).
* Step 1: Capturing
The capturing process involves having an idea or new task and writing it down somewhere where it can be
reviewed later.
An important thing to note is that the process of capturing *does not necessarily imply* the process of annotating.
Annotating is adding metadata like contexts, timeframes, associations (unique to Neorg) and projects. Those are
part of the Next Actions ontology, and are discussed later. They /can/ be also part of the capturing process (something
we call `preliminary information`), but for most cases they are not a requirement.
The capture mechanism is bound to `<LocalLeader><LocalLeader>` by default. It can be executed on /any/ file,
including non-norg files.
*** The User Interface
The user interface for capturing a note should be hilariously simple at first glance.
All the user should see is a text box with a prompt to press `?` for more information.
The expanded information should include the basic capture syntax.
The most basic capture syntax includes:
%TODO: add more syntax%
- Regular text - the normal content of the captured note.
- `#work` - a context, some circumstance that you can attach to the note itself.
- `@jeremy` - an association, an entity that is bound to the note in some way.
- `!1` - urgency, starting from 1 to infinity. One is the most urgent.
- `&tickler` - binds the content of your note to a specific {* ontologies}[ontology] alongside the default `&inbox` ontology.
- `~1{y[ear]|mo[nth]|w[eek]|d[ay]|h[our]|m[inute]}` - the estimated amount of time you expect the task to take you.
The content in square brackets is optional. Recommended to give yourself a rough estimate without setting a specific
due date.
*** Default Captured Information
When pressing the "capture" keybind, a default collection of information should be collected and stored
alongside the note, ready for the user to see when they are going through the processing phase.
This set of information includes:
- The exact date (down to the minute) the note was captured. Seconds should be omitted, as we would like to
minimize cognitive overhead.
- The name of the file and the line number where you got the idea - this should in most cases help as a context
where you got your "aha" moment.
*** Extra Captured Information
The user should be able to highlight some text in their current buffer before pressing the capture keybind
to attach the text (with appropriate syntax highlighting) to the note.
*** The User Experience
Punctuation tends to be a serious giveaway to the "tone" of a note. It could be sensible for Neorg to notice
that a note ends with a question mark, and therefore should by default put the note inside the `maybe/someday` ontology.
If the user during the processing phase changes their mind and does not decide to throw the item into the someday ontology
then the item can be happily pulled from under the rug.
*** Interesting Details
If a note contains preliminary information, it will first be put into the appropriate container as a "volatile" task.
It will behave just like any other task or idea, but it will /still/ be presented to the user during the processing phase.
It's during the processing phase that the user can then fully commit to their initial decisions or alter the metadata of the
task to repurpose it and move the task to a different container.
*** Other Capturing Mechanisms
Apart from this "quick capture", it would also make complete sense to support whole file captures, external resource captures
(URLs, PDFs), etc. each with their own UIs.
* Ontologies
Before any further explanations are made it's important to understand
/ontologies/ as a concept. This concept is general and exists in the whole of Neorg, but is extensively used
within the GTD implementation. Think of an ontology as a container with some
distinct properties. For starters, a single ontology contains any number of
elements of the same type. The type consists of the following:
- A text field (required)
- A `derives` clause (optional) - this merges the current ontology with another template ontology.
Useful to derive e.g. a `calendar` ontology which will force you to provide all of the data necessary
to display a calendar.
- A `display` clause (required) - how to display the data in the ontology, can be one of `list`, `graph`, `calendar`, `table`.
- Any set of keywords: `key \: Date|Text|File`. Some keywords can be marked as required,
while others optional.
In Neorg, *every GTD list is simply an ontology*. This includes the inbox, the next actions, tickler file, calendar, you name it.
Neorg binds your captured task to an ontology under the hood. Moving a task from the inbox to the next actions list is equivalent
to changing the ontology from `&inbox` to `&next-actions`, and letting the type system verify if all variables and data are in the right
place.
*** The Power of Data
Given ontologies are just generic containers, their data can be bent at the user's will. Data can be displayed as tables, lists, calendars
and others given the correct queries.
This means that, unlike GTD's lists, ontologies are not as tightly intertwined and are more flexible as a result. This means that any specific
list (e.g. the calendar) can be duplicated or its output modified (you can have several different calendars which are just
different ontologies with their `display`:s set to `calendar`).
The GTD implementation in Neorg works because Neorg's GTD provides a *default set of ontologies*
(with appropriate names like `&inbox`, `&calendar` etc.) crafted to mimic the GTD workflow in the most efficient way possible.
These ontologies are simply registered within the Neorg environment and are used appropriately.
* Processing
Processing is a very important part of your workflow. It involves going through each capture in the inbox
and deciding what the next course of action for that task should be. You perform processing whenever you have some spare time
to do some side tasks.
*** Processing View
There are a few ways you can process tasks, these are "one by one", "list view" and "calendar view":
- One by one - self explanatory, displays one task at a time, allowing you to make a conscious decision
for each task. Packed with one-key keybinds for most tasks (send to maybe/someday ontology, send to tickler file, archive).
- List view - for when you know you had some important things to do but do not want to sift through every SINGLE capture
you've made. Most urgent tasks should be displayed in red.
- Calendar view - since tasks are first sorted by urgency and then date created (ascending), it is also possible to display your
thoughts in the form of a calendar. Especially useful if your tasks are often time sensitive.
The order in which tasks are presented should be:
- Most urgent first, or
- Oldest first
*** Types of Actions
Depending on what you would like to do with the task you may opt for a set
of different actions:
- Add to the `maybe/someday` ontology, e.g. "learn Ithkuil".
- Convert to an `action` and move to Next Actions. By `action` we
mean an actual PHYSICAL thing you can do, instead of a hypothetical. E.g.
"plan cake lottery" -> "e-mail Arthur and Camille and remind them to bake
their cakes".
- If the task can be done in 2 minutes, DO NOW - the editor will enter a
state of "doing a task", and Neorg will remember across sessions that a
task is still in the process of being done.
- Move to Next Actions.
- Delegate to a timeframe/date - this will open up the calendar view with
all your other tasks and allow you to select when you want to assign the
task to be done.
- Delegate to "waiting for" ontology - if your task is being blocked by another person or
task you may move it to the "waiting for" ontology. If you have your associations and tasks
set up correctly Neorg will also be able to auto-detect when this task is no longer being "blocked".
- Move to a project (if the project doesn't exist, it will be created, else the task will be appended
to the end of the project).
- Archive the task.
- Place the task in the trash.
*** "Waiting for"
Talk about automatic unblocking of a task if your associations and tasks are set up correctly.
The unblocked task is moved back into the inbox.
Also talk about how waiting for's can have expected unblock dates (expected due dates)
as well as expected start dates just like a regular task. Neorg will then notify you if that
task is overdue or was done faster than you expected (useful if you want Neorg to tell you that
coworker Jimmy has been slacking on the side project for the past 2 weeks now).
*** UI/UX
- Each type of action should have a single mnemonic keybind bound to it regardless of the processing view.
- The default view should be a popup box in the middle of the screen with basic actions. Pressing `?<action-button>`
should display help related to that action.
- The user should additionally be able to press the `u` button to undo the last action and place the task back into the inbox.
%TODO: Describe UI for the other views%
*** Common Metadata Operations
When processing your tasks you should also verify preliminary metadata or assign metadata to your tasks.
During this stage, you may press any of the keybinds to apply any metadata. Press `C` to add a space separated list
of contexts, and press `<CR>` to apply. Press `A` to assign the note to a specific association.
Contrary to other GTD implementations, the user should also be able to press `Es` (estimated start date) or `Ed` (estimated due date)
to set a fuzzy date for when they expect the project to be complete or started. Not every task has a strict deadline, and you
definitely do not want to see tasks that actually *do* have a deadline shown with the same urgency as tasks that only
have an estimated deadline.
**** CONTEXTS vs ASSOCIATIONS
A /context/ is a general tag that you apply to your note - this includes the tools you might need to complete the task,
where the task needs to be completed, or a category that your task falls under.
An /association/ is just like a context but it has *permanent metadata* attached to it. This is especially useful for people
or locations. You may create an association to a coworker (think of it as a profile) with their name and surname
as permanent metadata. Then, when you're in a meeting with them, you may bring up your list of associations with that person
to see what you wanted to discuss with them.
* The Next Actions
The Next Actions is the list of items you visit when you're *going* to get
things done. Instead of hypotheticals or things that need to be expanded on,
you go through each item in the Next Actions ontology and get each item done.
This ontology displays the general items of the Next Actions as well as tasks
with upcoming due dates. By default, all items in a Next Actions have an
urgency of 10. Items that are part of the calendar (with marked due dates)
have their urgency equal to the amount of days left for the task (remember, 1
is the most urgent).
The Next Actions is displayed in whole, allowing you to choose what you would like to work on first. Items with
the highest urgency are displayed first, with every other item sorted by the estimated time that task will take,
otherwise by date created.
*** Facilities for Time Management
When you press `<CR>` to begin working on a task, Neorg enters a "task
pursuit" mode. It will provide live information about the due date, the time
spent daily on the task, completion rate (if you are working on a project).
The `:Neorg task` command should display this information in a single popup,
with the following abilities:
- Mark the task as complete.
- Temporarily pause - pause the current task (to go eat lunch, sleep, or
perform other intermediary activities). Closing all Neovim/client
instances will automatically signal to the GTD process to pause the task.
- Cancel the task (with a reason) - equivalent of moving to the archive.
- "Change your mind" - move to the `maybe/someday` ontology.
- Postpone the task (to a different date).
- Block the task (move to the "waiting for" ontology).
*** Pomodoro Integration
This wouldn't be the job of GTD itself, but a pomodoro plugin could hook into the currently active task,
provide metrics like "if you spend 40 minutes a day on this task it should be complete by x" and the usual
pomodoro features.
*** Statusline Integration
Neorg should provide statusline functions to display GTD progress, tasks left and other important bits of
information.
* Maybe/someday ontology
The m/s ontology is for thoughts or ideas that you are unsure about or do not have time to currently pursue.
They do not clog up your Next Actions nor the inbox, allowing you to keep the things you actually have to do
clean.
Items are moved here during the capturing phase or during the processing phase. The contents of this ontology
is reviewed ideally at the end of each week during the {* review process}, ensuring all of your cool ideas
are still under your consideration.
Contrary to other GTD implementations, the m/s ontology *also allows you to have projects within it*. It's common
to have an idea or concept that you might do someday, but you would like to have planned out in advance. It's also
an interesting way of procrastinating I guess :p
After a task receives a defined or estimated due/start date it will then be moved into your regular `&projects`
ontology where you can proceed to work on the project.
* Archive
The archive is where tasks that have been put down are placed. They're not entirely deleted and still
have a task ID, therefore they can still be referenced, but they are *not allowed to have any time-sensitive metadata*.
Any other metadata is retained, should the item be unarchived in the future.
For GTD `1.0.0`, the archive should be as simple as this. Just a container for tasks/notes that are no longer of interest.
In the future the capabilities of the archive may be expanded.
* Reference
The reference behaves similar to the archive in that it contains data that is not actively in use. Tasks in the reference,
however, may have *all of their metadata retained*, including time-sensitive metadata.
Data and tasks may be pulled from the reference, but the syntax for doing so is not yet established.
* Trigger List
A trigger list is a list of general errands that you do frequently. You go through the list and think to yourself
whether you have forgotten about anything from that given topic. Neorg will provide three different trigger lists
by default: a personal trigger list, a student trigger list and a work trigger list.
Below is an example snippet of a personal trigger list. If you ever remember anything about the presented topic capture it
to the inbox as soon as possible:
@code
- Projects started, not completed
- Projects that need to be started
- Commitments/promises to others
- Significant Other
- Family
- Friends
- Classmates
- Borrowed items
- Projects: other organizations
- Service
- Civic
- Volunteer
- Communications to make/get
- Family
- Friends
- Professional
- Initiate or respond to:
- Phone calls
- Text messages
- Voicemail
- E-mail
- Snail mail
- Social Media
- Upcoming events
- Special occasions
- Birthdays
- Anniversaries
- Weddings
- Graduations
- Holidays
- Travel
- Weekend trips
- Vacations
- Social events
- Cultural events
- Sporting events
- Things to do
- Places to go
- People to meet/invite
- Local attractions
- Administration
- Financial
- Bills
- Banks
- Investments
- Loans
- Taxes
@end
*** User Experience
Neorg will display trigger lists in a UI that will allow you to immediately add captures, closing the gap and making
the mental model of a trigger list easier to deal with.
* Review Process
The review process happens usually at the end of every week. It involves taking a look at your projects, next actions and
the amount of things you completed during the past week, and establishing a basic plan for next week.
*** Automating the Review Process
The user should be able to configure a static day of the week and time for a weekly review. Neorg will then
automatically fill the calendar entry at that point every week with the appropriate due date. Neorg will also be able
to calculate an estimated time (`~time`) of the whole review by doing some automatic, behind-the-scenes calculcations for
each sector of the review process. This includes:
- Counting the amount of projects that do not have a Next Action
- Checking if the Next Actions ontology is empty, but the inbox is not (there are tasks left to process)
- Counting the amount of overdue tasks
- Counting the amount of someday/maybe tasks (which should also be reviewed)
Based on usage data of the user (stored locally, of course) the average amount of time it takes to review a single task per sector
can be adjusted to more closely match the actual speed of the user.
The user may also opt not to set a static day for their review. If this is the case, Neorg may provide a yellow warning icon in the calendar
view which, when clicked or opened with the appropriate keybind, would notify the user that they have not set a review date.
This review date warning should also be configurable.
*** The Review Date UI/UX
It is important to operate within the limits of the TUI. The review process should be opened in a completely new tab, occupying the entire space
and allowing the user to fully immerse themselves in the review process.
Below is a prototype example of the UI.
@code
STEP 1/2
PAST PRESENT FUTURE
|-------------| |-------------| |-------------|
| Tasks | | | | Next |
| Completed | | OVERDUE | | Actions |
| | | | | |
| | -----> |-------------| -----> | |
| | |-------------| | |
| | | NO NEXT | | |
| | | | | |
| | | ACTIONS | | |
|-------------| |-------------| |-------------|
@end
The review involves all things you have done, the things you need to do, and the actions you should take to make your future self
more organized.
**** Tasks Completed
This display should show an overall percentage of what helped you achieve your goals.
It should show all projects that were fully completed and what projects you made progress in the most.
The last few lines should show the projects that haven't moved much.
**** Overdue
The overdue display should show all tasks that are currently overdue and must be handled in some way.
It should be possible to interact with the tasks directly from the UI with a similar set of keybinds
as the inbox processing phase (moving to archive, postponing etc.).
Tasks with the highest urgency should be displayed first.
**** NO NEXT ACTIONS
This display should show all projects that do not have another Next Action defined for them, with
the quick ability of adding a Next Action by showing the inbox in a popup.
If there are no next actions but there are items in the inbox then there should also be a message
telling the user they have no Next Actions defined.
**** Next Actions
The Next Actions display should show all of the next actions and allow you to verify if everything
is still the way you wanted it. Editing, deleting and modifying the tasks should be as simple as it
is in the other GTD UIs.
---
Apart from the physical past, present and future realms you can also press `<Tab>` to switch the view
to the /hypothetical/ realm, aka the maybe/someday ontology. The view is also automatically switched after
you have completed the first stage of your review.
In this view you will see all hypothetical projects and ideas that you had, segmented by last interacted/modified
and new ideas that you had in the last week, after which all other items from the ontology should follow.
Here you may delete, move, build out ideas and anything else you would normally do with your m/s ontology,
all with the same, familiar keybinds.
*** Trigger List Prompt
After a completed review, the user should also be prompted whether they would like to bring up their trigger list.
If yes, ask for the profile of the trigger list and display it to the user!
* The Calendar
The calendar is the most sophisticated GTD display.
An idea that the calendar /must/ understand is that *not all tasks are blocking*.
Additionally, not all tasks require your attention throughout the entire span
of doing the task. This is a serious shortcoming in most other time tracking applications,
as they force you to allocate time for things that should be able to easily overlap with other
tasks that you might want to do in the meantime.
The calendar implementation is detached from GTD, and GTD merely interacts with the calendar
to display information about upcoming, blocking/non-blocking, attentionful/attentionless tasks.
* Graphs
The easiest comparison to how a graph in GTD would look is similar to obsidian's graph view.
Many nodes are interconnected to show relationships between data.
Graphs will be rendered in a separate window from Neovim, as it is impossible to render good-looking
graphs with mere unicode. Graphs also play well with mouse inputs for dragging around and clicking, therefore
a GUI is almost critical for this task.
* Motivating the User
Neorg may opt to urge the user to get their tasks done every now and again
(obviously under a configuration option). When the user has a few tasks to
sift through, let them know they have not a lot left to go. If the user has a
lot of tasks in their inbox, urge them by saying that sifting through just a
few captures per day will quickly amount to serious progress. Do not let the
user's tasks feel stale.
The review process is usually seen as a chore, and therefore should be treated
in a lighthearted and cheerful manner. Even a simple "Good Job!" would be enough,
although we may want to have a streak system which counts how many times you've
consecutively done a review.
* Displays
Tasks are sometimes difficult to visualize, especially once they grow greatly. Below are some concepts
for making the visualization of tasks easier.
*** Display All Tasks Related to a Context
The following display could show all of the tasks that are related to a given context, a set of contexts (A or B)
or a union of contexts (A and B) in the form of a graph of connections.
*** Display Task Dependencies
The following display would be shown in the form of a mindmap. Projects would branch out into tasks, and tasks that
depend on other tasks would be marked with a one-way arrow.
* General Considerations
We should absolutely establish a single ruleset for how we set our keybinds. Currently they are a bit over the place.
* Storage
This section of the document covers how data is stored in the context of GTD. *All ontologies are stored as plain-text,
readable Norg files*. Specifically, every ontology is an /unordered/ list of tasks if it's a general container (e.g. a project, an archive).
If the data comes in the form of data that has to be processed in order (e.g. an inbox, a calendar, a trigger list) then the ontology
is an /ordered list/ of tasks.
There are some general rules that should be applied in all ontologies, and these are:
~ Use the default TODO syntax wherever possible. This includes done, undone, cancelled (archived) tasks alongside start dates, due dates and specific dates.
~ For more specific metadata, use `#` or `+` macro tags to signify more complex relationships (e.g. `#waiting.for <task-id>`)
A comprehensive list of macros will be released based on the demands of the implementation (no need to plan these out in the specification if most end up not
being used).