[!] restructure docs into Diátaxis quadrants - #822
Open
pashagolub wants to merge 19 commits into
Open
Conversation
pashagolub
force-pushed
the
docs/diataxis
branch
from
August 19, 2026 23:12
8f2dc8d to
a0c6cf6
Compare
how-to-write-yaml-chains.md re-documented every BUILTIN command's JSON parameter shape (Sleep, Log, SendMail, Download, Copy*) that already lives in reference-commands-tasks-chains.md#parameter-value-format, creating a third source of truth alongside yaml-format.md. Trim the 'Task Parameters' section to two representative YAML examples (SQL, PROGRAM) and link to the reference for the exhaustive BUILTIN shapes. Audit finding P0 #3.2 (docs-diataxis-audit.md).
YAML-authored chains shipped with a how-to and reference but no onboarding lesson, unlike the original SQL add_job() path. Add a second tutorial mirroring tutorial-first-chain.md's structure (sequential, no branching, visible result at every step) using a BUILTIN Log task on an @reboot schedule so the result is visible immediately after startup. Wire into mkdocs.yml nav and index.md. Audit finding P0 #3.1 (docs-diataxis-audit.md).
Learn More surfaced 4 links (one per quadrant) out of 18 doc pages, omitting YAML chains, the secret store, and OpenTelemetry entirely. Replace the one-per-quadrant listing with one entry per major feature area (chain scheduling, YAML authoring, secrets, observability), each linking its how-to/reference pair, plus a pointer to the sidebar nav for the rest. Audit finding P1 #3.4 (docs-diataxis-audit.md).
'You can temporarily skip a single step... by toggling the live flag' was instructional voice inside a Reference document (Diátaxis anti-pattern 3). Restate as a neutral fact about what the setting does; keep the SQL as an illustrative example, not an instruction. Audit finding P2 #3.7 (docs-diataxis-audit.md).
Pip requirements for mike/mkdocs-material are build tooling, not documentation content, and cluttered the docs/ content tree. Move to repo root and update build.yml's cache-dependency-path and install step accordingly. Audit finding P2 #3.6 (docs-diataxis-audit.md).
'Recommendations' in how-to-use-secret-store.md was advisory/opinion content (prefer X over Y, with rationale) — explanation-flavored material embedded in a how-to guide. Relocate it into explanation-secret-store-security-model.md as a 'Trade-offs Against Alternatives' section, where opinion and comparison are the expected mode, and replace it in the how-to with a link. Audit finding P2 #3.7 (docs-diataxis-audit.md).
The Overview section's bulleted benefits list ('Benefits include:
Creating complex multi-step workflows...') was 'why use this
feature' framing rather than 'how to use it' — mild teaching/
marketing tone in a document that should assume the reader already
decided to use YAML and wants the steps (Diátaxis anti-pattern 2).
Collapse to a single goal-oriented sentence.
Audit finding P2 #3.7 (docs-diataxis-audit.md).
Descriptive third-person voice ('This sample demonstrates...') read
as an annotated reference index rather than the goal-oriented How-to
Guide the nav places it under. Reword each heading and lead sentence
as an imperative goal ('Send an email from a chain', 'Run a task in
an autonomous transaction') to match its placement.
Audit finding P2 #3.8 (docs-diataxis-audit.md).
New docs already follow how-to-/reference-/explanation-/tutorial- prefixes; older files predate the convention and are not renamed (breaks external links and git blame). Capture the policy explicitly in CONTRIBUTING.md so future contributors follow it consistently. Audit finding P2 #3.5 (docs-diataxis-audit.md).
Source document for the fix commits that follow it in history (dedup, tutorial gap, stale ER diagram, index.md Learn More, narrative-voice leaks, requirements-doc.txt relocation, samples.md voice, filename convention). Kept at repo root as a point-in-time record, not part of the published docs/ site.
Error handling (ignore_error/on_error/autonomous) had how-to-level mentions and full reference coverage but no learning-oriented lesson, mirroring the earlier tutorial gap for YAML chains. Add a third tutorial: a chain that always fails, an on_error handler that counts recent failures and reschedules via notify_chain_start() with a doubling delay, verified end-to-end against a scratch PostgreSQL instance (retry sequence 5s/10s/20s, give-up on the 4th attempt). Inspired by samples/DelayedRetry.sql, simplified to a single path with no branching per tutorial conventions; links to the sample for the configurable, production-ready version. Wire into mkdocs.yml nav and index.md Learn More.
my_database=>/my_database-> prompt prefixes and leading '#' before pg_timetable invocations are psql's/a comment's own output, not something the user types — pasting them verbatim breaks psql (confirmed: 'ERROR: syntax error at or near "my_database"') or silently no-ops as a shell comment. Split every multi-line SQL block into a plain, paste-able command block plus a separate expected-output block across all three tutorials, and drop the leading '#' from the three pg_timetable run commands.
The secret store had how-to and reference coverage (how-to-use-secret-store.md,
secret_store.md, explanation-secret-store-security-model.md) but no
learning-oriented lesson. Add a fourth tutorial: install pgcrypto,
insert an encrypted timetable.secret row, wire a task's
database_connection to ${secret:name}, and observe the resolved
connection succeed while execution_log stays plaintext-free.
Verified end-to-end: built the actual pg_timetable binary and ran it
against a scratch PostgreSQL instance with the exact tutorial SQL/CLI
steps. Confirmed:
- chain/task creation must be name-keyed (CTE via chain_name), not
hardcoded chain_id=1/task_id=1 — a prior chain from another tutorial
in the same database already occupies id 1, which the first draft
missed and would have silently written into the wrong chain.
- the remote connection resolves and the task succeeds
('Task executed successfully', 'Chain executed successfully').
- timetable.execution_log.params/command never contain the plaintext
password (samples/RemoteDB.sql inspired the pattern; simplified to
tutorial length using execution_log itself as observable proof
instead of a dedicated remote-log table).
- actual log line format captured from a real run to keep the
illustrative log excerpt accurate.
Wire into mkdocs.yml nav and index.md Learn More.
background.md was thin (two sentences plus an external blog-post link list) and stale - the newest linked post predates v4 while the project is now at v7. Its two load-bearing facts (project origin, commercial support offering) now live in index.md's existing Contributing/Support sections instead of a separate Concept page. Removed the external blog-post list entirely rather than incorporate it; it's marketing history, not documentation content, and the announcement post already returns HTTP 403. Drop the 'Project Background' nav entry and its Learn More link; update CONTRIBUTING.md's legacy-filename exception list to match.
Sourced from the 2022 blog post 'Run multiple jobs but limit number of sessions' (Github discussions #427/#428). Classified How-to (goal-oriented, assumes competence, conditional imperatives) rather than reproducing the Q&A narrative. Verified the max_conn = cron-workers + interval-workers + 3 formula against internal/pgengine/bootstrap.go and confirmed it empirically: built the binary, ran it with --cron-workers=2 --interval-workers=2 against a scratch PostgreSQL instance, observed exactly 7 rows in pg_stat_activity and timetable.active_session throughout a burst of 10 self-destructing max_instances=1 chains (never grew with queue depth - active_session tracks the fixed connection pool, not one row per chain, correcting a common misreading of the original post). Also verified the channel-overflow scenario is far less likely to recur today than in 2022: v4.3.0 (Nov 2021, predating the post) already bumped the scheduler-to-worker channel to a 1024-chain minimum buffer. Reproduced with 1100 queued @reboot chains against 2+2 workers - no 'Failed to send chain' error, confirming the guidance should frame it as a backlog symptom rather than a routine spike. Dropped from the source post: the Q&A framing, the discussion-thread retelling, and blog boilerplate (newsletter/social links, sign-off). Added a monitoring step (pg_stat_activity query) tying the reference formula to an observable check the reader can run themselves.
pashagolub
force-pushed
the
docs/diataxis
branch
from
August 19, 2026 23:41
a0c6cf6 to
9c8b920
Compare
Coverage Report for CI Build 32314322639Warning No base build found for commit Coverage: 89.614%Details
Uncovered ChangesNo uncovered changes found. Coverage RegressionsRequires a base build to compare against. How to fix this → Coverage Stats
💛 - Coveralls |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.