timescale.info#185 · Help: docs/ as the site runs, a user guide, an FAQ and search (#172, part 1)
- timeline-app
- pull request
Part 1 of #172. This covers: - the manual; - the FAQ; - topic search; - everything from `docs/`, current with the code; - the API docs. The interactive tour and the "?" buttons with tooltips follow in a second PR. ## The help area (`/help`) - **Read live:** it reads `docs/` and the README as the server runs (`server/help.mjs`). Whatever is on `main` when a server is built is what its help says, with no separate copy to keep in step. - The Docker image, the server packages and the platform tarball ship `docs/` through Next's file tracing. - **Sections:** - Start here: guide, FAQ and the project overview. - Making timelines. - Sharing and working together. - Accounts and the API, which includes the HTTP API reference from #183. - Running a server. - How it works. - **Each page:** a contents box, and a note naming the file it comes from. Links between docs open as help pages, keeping their `#anchors`. Links to other files in the repository go to GitHub. - **Search:** `/help?q=…` searches every page's sections. A section must mention every word, and a word in its heading counts most. Results show snippets with the words marked. - **Where it's linked:** **Help** in the header and footer, and the sitemap. - **Markdown:** rendered by a small renderer in `server/help.mjs`, which covers what the docs use: headings with GitHub's anchors, nested lists, tables, fenced code, emphasis and links. Text is escaped, and no dependency is added. ## New pages - **`docs/guide.md`, "Using OpenChronology":** the manual to read first, task by task, covering: - what a timeline is and where it's kept; - getting started and moving around; - moments, durations, relationships and tags; - search, display settings, saving and revisions; - sharing, working together and comparing; - bulk changes, plugins, large timelines and keyboard shortcuts. - **`docs/faq.md`:** 30 common questions, from "Where is my data kept?" to running your own server. Every label, shortcut and number in both was checked against the code. ## Docs corrected Writing the guide found four places that no longer matched the app: - **README:** tapping empty space selects a time; it no longer creates an event. - **`retention.md` and `collaboration.md`:** the setting is the **Stop keeping saved history…** button, not a "Keep saved history" switch. - **`plugins.md`:** moment details now have **Save** and **Cancel**, and a new moment joins the timeline when saved. ## Tests - **`test/help.test.mjs`:** - the Markdown cases the docs use; - every doc renders with no Markdown left over; - every doc is in a section; - every link between docs leads to a page and heading that exist; - every link to a repository file names one that exists; - search behaves as described. A doc added later without a section, or a broken anchor, fails it. - **`next-platform.mjs`:** - `/help`, a page and its anchors, search, and a missing page's 404; - the help page uses the content security policy's nonce; - the header link to Help. Locally, all of the following pass: - 283 unit tests and typecheck; - the 11 browser suites; - the platform test. I also checked the pages by eye at desktop and phone widths.