From 08faac957a2148ce360e40a8071f1e2c19296b8a Mon Sep 17 00:00:00 2001
From: "Dustin J. Mitchell" <dustin@mozilla.com>
Date: Sun, 29 Nov 2020 20:14:06 -0500
Subject: [PATCH] Add a getting-started section

---
 docs/src/SUMMARY.md   | 23 ++++++++--------
 docs/src/internals.md |  5 ++++
 docs/src/welcome.md   | 61 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 78 insertions(+), 11 deletions(-)
 create mode 100644 docs/src/internals.md
 create mode 100644 docs/src/welcome.md

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index b37148b77..40871f638 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -1,13 +1,14 @@
 # Summary
 
-- [Installation](./installation.md)
-- [Usage](./usage.md)
----
-- [Data Model](./data-model.md)
-  - [Replica Storage](./storage.md)
-  - [Task Database](./taskdb.md)
-  - [Tasks](./tasks.md)
-- [Synchronization and the Sync Server](./sync.md)
-  - [Synchronization Model](./sync-model.md)
-  - [Server-Replica Protocol](./sync-protocol.md)
-  - [Planned Functionality](./plans.md)
+- [Welcome to TaskChampion](./welcome.md)
+  - [Installation](./installation.md)
+  - [Usage](./usage.md)
+- [Internal Details](./internals.md)
+  - [Data Model](./data-model.md)
+    - [Replica Storage](./storage.md)
+    - [Task Database](./taskdb.md)
+    - [Tasks](./tasks.md)
+  - [Synchronization and the Sync Server](./sync.md)
+    - [Synchronization Model](./sync-model.md)
+    - [Server-Replica Protocol](./sync-protocol.md)
+    - [Planned Functionality](./plans.md)
diff --git a/docs/src/internals.md b/docs/src/internals.md
new file mode 100644
index 000000000..7cc36ac29
--- /dev/null
+++ b/docs/src/internals.md
@@ -0,0 +1,5 @@
+# Internal Details
+
+The following sections get into the details of how TaskChampion works.
+None of this information is necessary to use TaskChampion, but might be helpful in understanding its behavior.
+Developers of TaskChampion and of tools that integrate with TaskChampion should be familiar with this information.
diff --git a/docs/src/welcome.md b/docs/src/welcome.md
new file mode 100644
index 000000000..948ceac93
--- /dev/null
+++ b/docs/src/welcome.md
@@ -0,0 +1,61 @@
+# TaskChampion
+
+TaskChampion is a person task-tracking tool.
+It works from the command line, with simple commands like `task add "fix the kitchen sink"`.
+It can synchronize tasks on multiple devices, and does so in an "offline" mode so you can update your tasks even when you can't reach the server.
+If you've heard of [TaskWarrior](https://taskwarrior.org/), this tool is very similar, but actively maintained and with a more reliable synchronization system.
+
+## Getting Started
+
+> NOTE: TaskChampion is still in development and not yet feature-complete.
+> This section is limited to completed functionality.
+
+Once you've [installed TaskChampion](./installation.md), your interface will be via the `task` command.
+Start by adding a task:
+
+```shell
+$ task add "learn how to use taskchampion"
+added task ba57deaf-f97b-4e9c-b9ab-04bc1ecb22b8
+```
+
+You can see all of your pending tasks with `task pending`, or just `task` for short:
+
+```shell
+$ task
+ id act description                   
+ 1      learn how to use taskchampion
+```
+
+Tell TaskChampion you're working on the task, using the shorthand id:
+
+```shell
+$ task start 1
+```
+
+and when you're done with the task, mark it as complete:
+
+```shell
+$ task done 1
+```
+
+## Synchronizing
+
+Even if you don't have a server, it's a good idea to sync your task database periodically.
+This acts as a backup and also enables some internal house-cleaning.
+
+```shell
+$ task sync
+```
+
+Typically sync is run from a crontab, on whatever schedule fits your needs.
+
+To synchronize multiple replicas of your tasks, you will need a sync server and a client ID on that server.
+Configure these in `~/.config/taskchampion.yml`, for example:
+
+```yaml
+server_client_id: "f8d4d09d-f6c7-4dd2-ab50-634ed20a3ff2"
+server_origin: "https://taskchampion.example.com"
+```
+
+The next run of `task sync` will upload your task history to that server.
+Configuring another device identically and running `task sync` will download that task history, and continue to stay in sync with subsequent runs of the command.