Skip to content

Commit 6a7043b

Browse files
lcorrigan704lcorrigan704
authored
Merge pull request #24 from lcorrigan704/docs/add-user-documentation-to-wiki
created wiki user docs for this project
2 parents 6dd7b36 + 19dde3f commit 6a7043b

31 files changed

Lines changed: 1127 additions & 0 deletions

‎.github/pull_request_template.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,7 @@
1010
## Checklist
1111
- [ ] I have tested these changes locally
1212
- [ ] I have updated documentation where needed
13+
- [ ] I reviewed docs impact and updated impacted pages under `docs/wiki/`
14+
- [ ] I updated `docs/wiki/Docs-Freshness.md` (or marked N/A with reason)
15+
- [ ] I ran `bash scripts/wiki-validate.sh` locally (or CI covers this)
1316
- [ ] I have considered migrations or data impacts

‎.github/workflows/wiki-docs-check.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: Wiki Docs Check
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- 'docs/wiki/**'
7+
- 'scripts/wiki-*.sh'
8+
- '.github/pull_request_template.md'
9+
push:
10+
branches: [main]
11+
paths:
12+
- 'docs/wiki/**'
13+
- 'scripts/wiki-*.sh'
14+
15+
jobs:
16+
validate:
17+
runs-on: ubuntu-latest
18+
steps:
19+
- name: Checkout
20+
uses: actions/checkout@v4
21+
22+
- name: Setup Node
23+
uses: actions/setup-node@v4
24+
with:
25+
node-version: '20'
26+
27+
- name: Build docs index
28+
run: bash scripts/wiki-build-index.sh
29+
30+
- name: Validate docs
31+
run: bash scripts/wiki-validate.sh
32+
33+
- name: Validate wiki sync dry-run
34+
run: bash scripts/wiki-sync.sh --dry-run

‎docs/wiki/Clients.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Clients
2+
3+
## Purpose
4+
Create and maintain client records used by invoices, quotes, agreements, proposals, and expenses.
5+
6+
## Before You Start
7+
- Active workspace is correct.
8+
- You have create/edit permissions.
9+
10+
## Steps
11+
1. Open Clients page.
12+
2. Select New client.
13+
3. Enter core fields (name, emails, phone, company, website, address).
14+
4. Save client.
15+
5. Use row actions to edit or delete clients.
16+
17+
## Expected Result
18+
Client appears in client table and in related entity selectors.
19+
20+
## Common Mistakes
21+
- Missing invoice email/contact email before sending billing emails.
22+
- Deleting a client without checking linked downstream records.
23+
24+
## Related Tasks
25+
- [Invoices](./Invoices)
26+
- [Quotes](./Quotes)
27+
- [Service Agreements](./Service-Agreements)
28+
- [Proposals](./Proposals)
29+
- [Expenses](./Expenses)

‎docs/wiki/Danger-Zone.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Danger Zone
2+
3+
## Purpose
4+
Safely operate destructive and recovery actions with explicit scope controls.
5+
6+
## Before You Start
7+
- Confirm active workspace.
8+
- Take a backup before any destructive action.
9+
10+
## Steps
11+
1. Open Settings > Danger zone.
12+
2. Use Workspace danger for active workspace operations:
13+
- Reset business data (workspace only)
14+
- Delete workspace (typed workspace name confirmation)
15+
3. Use System danger for backup/restore:
16+
- Create backup with scope:
17+
- Active workspace only
18+
- Entire tenant (all workspaces)
19+
- Restore backup with typed company confirmation and restored workspace name.
20+
21+
## Expected Result
22+
Only intended scope is affected, with typed confirmations reducing accidental data loss.
23+
24+
## Common Mistakes
25+
- Running tenant restore when only workspace restore intent exists.
26+
- Attempting to delete last remaining workspace (blocked).
27+
28+
## Related Tasks
29+
- [Workspace Management](./Workspace-Management)
30+
- [Operations Runbook](./Operations-Runbook)

‎docs/wiki/Docs-Freshness.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Docs Freshness
2+
3+
## Purpose
4+
Track documentation ownership and review recency for major feature areas.
5+
6+
## Before You Start
7+
- Update this table when any user-facing behavior changes.
8+
9+
## Steps
10+
1. Identify impacted feature area(s).
11+
2. Update last-reviewed date and owner.
12+
3. Link related PR and wiki page(s).
13+
14+
## Expected Result
15+
Teams can quickly identify stale docs and ownership.
16+
17+
## Common Mistakes
18+
- Merging UX changes without updating freshness metadata.
19+
20+
## Related Tasks
21+
- [Documentation Standards](./Documentation-Standards)
22+
23+
## Freshness Table
24+
25+
| Feature Area | Wiki Page | Owner | Last Reviewed | Related PR |
26+
|---|---|---|---|---|
27+
| Workspace Management | Workspace-Management | @owner | 2026-04-05 | TBD |
28+
| Clients | Clients | @owner | 2026-04-05 | TBD |
29+
| Invoices | Invoices | @owner | 2026-04-05 | TBD |
30+
| Quotes | Quotes | @owner | 2026-04-05 | TBD |
31+
| Revenue Adjustments | Revenue-Adjustments | @owner | 2026-04-05 | TBD |
32+
| Service Agreements | Service-Agreements | @owner | 2026-04-05 | TBD |
33+
| Proposals | Proposals | @owner | 2026-04-05 | TBD |
34+
| Expenses | Expenses | @owner | 2026-04-05 | TBD |
35+
| Emails Workspace | Emails-Workspace | @owner | 2026-04-05 | TBD |
36+
| Tax Workspace | Tax-Workspace | @owner | 2026-04-05 | TBD |
37+
| Settings + Danger Zone | Settings / Danger-Zone | @owner | 2026-04-05 | TBD |

‎docs/wiki/Documentation-Standards.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Documentation Standards
2+
3+
## Purpose
4+
Define how wiki docs are authored, reviewed, and maintained.
5+
6+
## Before You Start
7+
- Source-of-truth is repo docs under docs/wiki.
8+
- Wiki pages are generated/synced from this directory.
9+
- Use file names in `Title-Case-With-Hyphens.md`.
10+
11+
## Steps
12+
1. Create or update page using templates in docs/wiki/_templates.
13+
2. Ensure every task page includes sections:
14+
- Purpose
15+
- Before You Start
16+
- Steps
17+
- Expected Result
18+
- Common Mistakes
19+
- Related Tasks
20+
3. Add page to docs/wiki/nav.json.
21+
4. If UI changed materially, add/update screenshot in docs/wiki/assets.
22+
5. Keep labels/status names exactly aligned to in-app text.
23+
6. Add workspace vs tenant scope notes for any behavior that can differ by scope.
24+
7. Run docs checks and wiki sync dry-run:
25+
- `bash scripts/wiki-build-index.sh`
26+
- `bash scripts/wiki-validate.sh`
27+
- `bash scripts/wiki-sync.sh --dry-run`
28+
8. Sync to GitHub Wiki when ready:
29+
- `bash scripts/wiki-sync.sh --wiki-dir ../<repo>.wiki`
30+
- add `--push` to commit/push wiki repo changes.
31+
32+
## Expected Result
33+
Docs remain consistent, discoverable, and safe to publish to wiki.
34+
35+
## Common Mistakes
36+
- Adding page without nav.json entry.
37+
- Using UI labels that do not match current product text.
38+
- Adding excessive screenshots where simple steps are clearer.
39+
- Forgetting to update freshness ownership/date table.
40+
41+
## Related Tasks
42+
- [Docs Freshness](./Docs-Freshness)
43+
- [Home](./Home)

‎docs/wiki/Emails-Workspace.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Emails Workspace
2+
3+
## Purpose
4+
Use the multi-entity composer to generate grouped drafts and send operational emails with attachments.
5+
6+
## Before You Start
7+
- SMTP configured in Settings for send actions.
8+
- Active workspace is correct.
9+
10+
## Steps
11+
1. Open Operations > Emails.
12+
2. Select entities (invoice, quote, proposal, agreement, expense).
13+
3. Generate drafts.
14+
4. Review client-grouped drafts.
15+
5. Edit recipient, subject, and body per group.
16+
6. Use actions menu per draft:
17+
- Send via SMTP
18+
- Copy body / subject+body
19+
- Open mail client
20+
- Download attachments
21+
7. Use Send All with confirmation dialog for batch dispatch.
22+
8. Review email logs; resend or mark delivered (single/bulk).
23+
24+
## Expected Result
25+
Drafts are grouped by client, send results are visible, and audit logs are retained in app.
26+
27+
## Common Mistakes
28+
- Sending without recipient email configured.
29+
- Expecting one global send failure to block all other groups (partial success is possible).
30+
31+
## Related Tasks
32+
- [Invoices](./Invoices)
33+
- [Quotes](./Quotes)
34+
- [Proposals](./Proposals)
35+
- [Service Agreements](./Service-Agreements)
36+
- [Expenses](./Expenses)

‎docs/wiki/Expenses.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Expenses
2+
3+
## Purpose
4+
Track expenses with tax metadata, receipts, and optional client/user attribution.
5+
6+
## Before You Start
7+
- Active workspace is correct.
8+
- Understand VAT registration state in settings.
9+
10+
## Steps
11+
1. Open Operations > Expenses.
12+
2. Create expense record.
13+
3. Use receipts child dialog to add/remove receipt files.
14+
4. Apply tax code/rate/mode (VAT fields shown according to registration state).
15+
5. Save expense.
16+
6. Use compose/PDF/export and edit/delete actions as needed.
17+
18+
## Expected Result
19+
Expense appears with totals, receipts, and tax metadata for reporting.
20+
21+
## Common Mistakes
22+
- Assuming VAT fields always appear when workspace is not VAT-registered.
23+
- Missing incurred date causing period filter confusion.
24+
25+
## Related Tasks
26+
- [Tax Workspace](./Tax-Workspace)
27+
- [Emails Workspace](./Emails-Workspace)

‎docs/wiki/Getting-Started.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Getting Started
2+
3+
## Purpose
4+
Provide the shortest path from first login to live operational usage.
5+
6+
## Before You Start
7+
- You have environment access and a valid account.
8+
- At least one workspace exists.
9+
10+
## Steps
11+
1. Sign in using the login screen.
12+
2. Confirm active workspace in the workspace switcher (top of sidebar).
13+
3. Set your financial year filter in the sidebar.
14+
4. Open `Settings` and verify company profile, prefixes, and SMTP.
15+
5. Create one test client, then create a quote or invoice.
16+
6. Use `Emails` to generate/send a draft with attachments.
17+
18+
## Expected Result
19+
You can navigate the app, create core records, and perform outbound communication.
20+
21+
## Common Mistakes
22+
- Starting data entry before confirming active workspace.
23+
- Forgetting to configure SMTP before testing reminders/send flows.
24+
25+
## Related Tasks
26+
- [Onboarding and Authentication](./Onboarding-and-Authentication)
27+
- [Workspace Management](./Workspace-Management)
28+
- [Settings](./Settings)

‎docs/wiki/Home.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Home
2+
3+
## Purpose
4+
This wiki explains how to use the Client Management System (CMS) as an end user/operator.
5+
6+
## Before You Start
7+
- You are logged in and can access at least one workspace.
8+
- You know whether your action should apply to the active workspace or the full tenant.
9+
10+
## Steps
11+
1. Start with [Getting Started](./Getting-Started).
12+
2. Use [Navigation and Financial Year Filter](./Navigation-and-Financial-Year-Filter) to understand cross-page filtering.
13+
3. Use [Wiki Index](./INDEX) for full page navigation by feature area.
14+
4. Open the workflow page for the task you want to complete.
15+
16+
## Expected Result
17+
You can complete core operational tasks without development support.
18+
19+
## Common Mistakes
20+
- Performing actions in the wrong workspace context.
21+
- Confusing workspace-scoped actions with tenant-wide backup/restore actions.
22+
23+
## Related Tasks
24+
- [Workspace Management](./Workspace-Management)
25+
- [Settings](./Settings)
26+
- [Danger Zone](./Danger-Zone)
27+
- [Troubleshooting and FAQ](./Troubleshooting-and-FAQ)
28+
29+
---
30+
31+
## Page Index
32+
33+
### Core
34+
- [Getting Started](./Getting-Started)
35+
- [Navigation and Financial Year Filter](./Navigation-and-Financial-Year-Filter)
36+
- [Onboarding and Authentication](./Onboarding-and-Authentication)
37+
38+
### Workspaces
39+
- [Workspace Management](./Workspace-Management)
40+
41+
### Entities
42+
- [Clients](./Clients)
43+
- [Invoices](./Invoices)
44+
- [Quotes](./Quotes)
45+
- [Revenue Adjustments](./Revenue-Adjustments)
46+
- [Service Agreements](./Service-Agreements)
47+
- [Proposals](./Proposals)
48+
- [Expenses](./Expenses)
49+
50+
### Operations
51+
- [Emails Workspace](./Emails-Workspace)
52+
- [Tax Workspace](./Tax-Workspace)
53+
- [Settings](./Settings)
54+
- [Danger Zone](./Danger-Zone)
55+
56+
### Support
57+
- [Troubleshooting and FAQ](./Troubleshooting-and-FAQ)
58+
- [Operations Runbook](./Operations-Runbook)
59+
60+
### Docs Governance
61+
- [Documentation Standards](./Documentation-Standards)
62+
- [Docs Freshness](./Docs-Freshness)

0 commit comments

Comments
 (0)