commit d6a77dbb0e2fc59aebe19512b5fd8f854ed16e9a Author: holo Date: Mon Oct 6 22:50:14 2025 +1000 Add docs diff --git a/Home.md b/Home.md new file mode 100644 index 0000000..7dce96e --- /dev/null +++ b/Home.md @@ -0,0 +1,233 @@ +# Task Management Commands + +Our tasklist system helps you track and share your current task (`!now`), +plan your future tasks (`!plan`), +and review your completed task history along with how long each task took (`!history`). + +**Note:** All commands use the `!` prefix (e.g., `!now`). + +--- + +## ⚙️ Track and share what you are working on (Single Task Usage) + +These commands are for managing the single task you are actively working on. +The flow is simple. Use `!now task` to show you are working on `task`, +and then write `!done` to mark it complete and see how long you worked on it. +If you want to mark your task complete *and* start another task, you can do +`!next anther task` instead. +If you discover you have made a typo, you can edit with `!edit another task`, +and at any time you can get rid of it entirely with `!clear`. + +| Command | Description | Example | +| --------------- | --------------- | --------------- | +| `!now [new task]` | Set or check your current task | `!now Write documentation` | +| `!notnow` | Pause your task (resume it with `!next`) | `!notnow` | +| `!next [another task]` | Complete your current task and start `another task` | `!next Take a break` | +| `!edit ` | Edit the text of your current task to `new task` | `!edit Make coffee` | +| `!done` | Complete your current task without starting a new one. | `!done` | +| `!clear` | Unset your current task. | `!clear` | + +## 📝 Making and managing a plan + +Sometimes, setting a single task isn't enough! +Maybe you want to remind yourself about something you need to do later (`!plan task`), +or you want to schedule your next few tasks for a seamless flow (`!now task1; task2; task3` and then `!next`). +Or sometimes half way through one task, you need to start another one, +but you don't want to lose the first task or the time tracked on it (`!sidequest`). + +Now presenting to you, your `!plan`! +This feature is under active development, so there may be some mild instability or deviations +from what is written here until I can get the documentation updated, sorry about that! +If there are any features you would like to see added or changed, +or anything you find confusing, please let me know so everyone can benefit from improvements! +Candid feedback is *always* welcome. + +In the below table, `taskspec` stands for a specification of one or more tasks in any of the following forms: + +- A single task, e.g. `Writing documentation` +- A single task number, e.g. `6` +- A *range* of task numbers, e.g. `6-10` +- Any combination of the above separated with semicolons, e.g. `6; Writing Documents; 8-10; Take a break` + +Note: Commas `,` *can* also be used to separate tasks, but semicolons are preferred. +In particular, `this, that; the other` represents *two* tasks, `this, that` and `the other`. +However, `this, that` alone represents the tasks `this` and `that`. +We generally recommend avoiding using commas in your tasks, but if you need to +you can take advantage of this behaviour by using trailing semicolons, for example, +`!now this, that;` will set your current task to just `this, that`. + +| Command | Description | Example | +| --------------- | --------------- | --------------- | +| `!now ` | Set your current task(s). If multiple are given, all tasks are added to the *start* of your plan. | `!now Read; Write` | +| `!next` | Complete your current task and start the first (incomplete) task on your plan. | `!next` | +| `!next ` | Complete your current task, and start the first task in `taskpec`. If multiple tasks are given, add all tasks to the *start* of your plan. | `!next Do exercises; Check exercises` | +| `!sidequest ` | Pause your current task (put it on the start of the plan) and start `other task` | `!sidequest Choose music` | +| `!done ` | Mark all tasks in `taskspec` as complete. You *can* create new tasks here and mark them as done. | `!done 10-20; Wash the plates` | +| `!plan` | Show the incomplete tasks remaining on your plan. | `!plan` | +| `!plan ` | Add all provided tasks to the *end* of your plan. | `!plan Do 10 pushups; Drink water` | +| `!unplan` | Remove all your tasks from your plan (does not delete them) | `!unplan` | +| `!unplan ` | Remove the specified tasks from your plan | `!unplan 1-5, 8, 9` | +| `!clear all` | Delete ***all*** the tasks on your tasklist. | `!clear all` | +| `!clear done` | Delete all the completed tasks on your tasklist (this will change your task numbers!) | `!clear done` | +| `!clear ` | Delete the tasks in `taskspec` | `!clear 1, 3, 10-20` | + +## 📜 Statistics and History + +It's satisfying to tick tasks off the tasklist! +It's even more satisfying to see how much we have done! +And for those of us who like data or don't use an external time tracker, +it's useful to see how long each task took to revise our future estimates! + +| Command | Description | Example | +| --------------- | --------------- | --------------- | +| `!history` | (Only on Discord) Show a paged list of tasks completed on each day. | `!history` | + +## Command Reference + +### `!now [taskspec]` + +The 'main' task of the task system, this sets or checks your current task(s). + +- **Aliases:** `!task`, `!check` +- With no arguments, this shows you your current task and how long you've been working on it. +- If `taskspec` describes a single task, sets this as your current task without modifying your plan. +- If `taskspec` describes multiple tasks, sets the first one as your current task, and adds all the tasks to the *start* of your plan. If the tasks were already in your plan, they get pulled to the front. + +#### Examples + +- `!now Writing my thesis proposal` + - Sets your current task. +- `!now` + - Replies: `You have been working on 'Writing my thesis proposal' for 15 minutes` +- `!now Prepare lecture notes; Grade assignments` + - Sets "Prepare lecture notes" as your current task and adds "Prepare lecture notes" and "Grade assignments" to the start of your plan. + +--- + +### `!notnow` + +Pauses your current task and moves it to the start of your plan. This is useful if you get interrupted and want to resume later. +Resume the task by writing `!next` which will resume that task. + +- **Aliases:** `!pause` + +#### Example + +- `!notnow` + - Replies: `Unset your task '#12: Writing my thesis proposal' and pushed it onto your plan! Use !next when you want to resume it.` + +--- + +### `!next [taskspec]` + +Completes your current task and starts your next one. + +- With no arguments, this will start the *first incomplete task* on your `!plan`. +- If `taskspec` describes a single task, sets this as your current task without modifying your plan. +- If `taskspec` describes multiple tasks, sets the first one as your current tasks, and adds all the tasks to the start of your plan. + +#### Examples + +- `!next` + - Replies: `Good work finishing 'Writing my thesis proposal', you worked on it for 1 hour 2 minutes. Started your next task 'Grade assignments', good luck!` +- `!next Take a break` + - Completes your current task and starts "Take a break". +- `!next Make coffee; Drink Coffee` + - Completes your current task, starts `Make Coffee`, and adds `Make Coffee` and `Drink Coffee` to the start of your plan. + +--- + +### `!done [taskspec]` + +Marks one or more tasks as complete without starting a new one. + +- With no arguments, completes your current task and show you how long you worked on it. +- If `taskspec` is given, this will complete all the (incomplete) tasks in `taskspec`. + - Tasks *may* be created and immediately completed, for the sweet satisfaction of ticking off something you have done. + +#### Examples + +- `!done` + - Marks your current task as finished. +- `!done 15` + - Completes the task number 15. +- `!done 15-20, Responded to emails` + - Completes the tasks `15, 16, 17, 18, 19, 20`, and creates and immediately completes the task "Responded to emails". + +--- + +### `!edit ` + +Edits the description of your current task. + +NOTE: Soon to be `!edit [n] ` for editing a task that is not your current one. + +#### Example + +- `!edit Studying triangulated categories` + - Replies: `Updated your current task!` + +--- + +### ### `!sidequest ` + +Put your current task on the head of the plan, and start a new task. + +This has the effect of pausing your current task to work on the provided new task, +and is particularly useful for 'temporary' tasks that interrupt the main task. + +When you finish the sidequest task with `!next`, you'll resume your main task. + +- **Aliases:** `!switch` +- If `taskspec` represents multiple tasks, they will all be put on the plan as usual, and your previous current task will be pushed down into the plan. + +#### Example + +- You are working on "Writing my thesis proposal". +- `!sidequest Make a cup of tea` + - Replies: `Started your sidequest 'Make a cup of tea', good luck! When you are done use '!next' to resume your main quest '#12: Writing my thesis proposal'.` + +--- + +### `!plan [taskspec]` + +View your remaining planned tasks, or add tasks to the *end* of your plan. + +- **Aliases:** `!later` +- Without arguments, shows you a list of all your incomplete planned tasks. +- If `taskspec` is given, adds all the specified tasks to the *end* of your plan, in the same order they are given. + +#### Examples + +- `!plan` + - Replies: `You have 2 tasks on the plan, good luck: #14: Grade assignments ┆ #15: Buy groceries` +- `!plan Go to the gym; 15` + - Adds "Go to the gym" to the end of your plan, and moved `15` to the end after that. The result will be: + - `#14: Grade assignments ┆ #16: Go to the gym ┆ #15: Buy groceries` + +--- + +### `!clear [target]` + +Deletes tasks from your list. Once deleted, tasks cannot be recovered! + +- **Aliases:** `!remove`, `!delete`, `!del` + +The `target` can be one of the following: + +- (nothing) or `current`: Deletes your current task. +- `plan`: Removes all tasks from your plan (does not delete them). +- `done`: Deletes all completed tasks from your tasklist (this will change your task numbers!). +- `all`: Deletes **all** of your tasks, including current, planned, and completed. +- `taskspec`: Deletes the specified tasks. You can't create new tasks here. + +--- + +### `!history` + +Displays a detailed history of your completed tasks, grouped by day. + +- **Aliases:** `!hist`, `!taskhist` +- **Platform:** Discord only. + +This command generates paginated tables showing which tasks you completed on which days, including start/end times and total duration.