diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..56dd733 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "wiki"] + path = wiki + url = https://github.com/OpenKotOR/TalkEd.wiki.git diff --git a/docs/plans/2026-05-27-repo-hardening-plan.md b/docs/plans/2026-05-27-repo-hardening-plan.md index 431a345..b773554 100644 --- a/docs/plans/2026-05-27-repo-hardening-plan.md +++ b/docs/plans/2026-05-27-repo-hardening-plan.md @@ -1,7 +1,7 @@ --- title: TalkEd Repo Hardening Plan date: 2026-05-27 -status: active +status: completed --- ## Overview diff --git a/docs/plans/2026-05-27-wiki-submodule-docs-plan.md b/docs/plans/2026-05-27-wiki-submodule-docs-plan.md new file mode 100644 index 0000000..3413e96 --- /dev/null +++ b/docs/plans/2026-05-27-wiki-submodule-docs-plan.md @@ -0,0 +1,94 @@ +--- +title: TalkEd Wiki Submodule And User Docs Plan +date: 2026-05-27 +status: active +--- + +## Overview + +Create a top-level git submodule named `wiki` that tracks the repository's own GitHub wiki repository, then populate the wiki with plain-language documentation for non-technical users. + +## Problem Frame + +The project now has repository-level guidance for contributors, but non-technical end users still lack an easy, central documentation surface that explains what TalkEd is, what it can and cannot do, and how to use it safely. + +## Scope Boundaries + +In scope: + +- Add a git submodule at `wiki/` pointing to `https://github.com/OpenKotOR/TalkEd.wiki.git`. +- Add comprehensive wiki markdown pages focused on non-technical usage. +- Cover app purpose, basic workflows, limitations/scope, common issues, and glossary content. + +Out of scope: + +- Changes to Delphi source or UI/resource files. +- Native build system changes. +- Workflow or governance refactors unrelated to wiki docs. + +## Key Decisions + +- Keep wiki docs plain-language first, with minimal jargon and explicit "what this means" phrasing. +- Use page-level navigation from `Home.md` so users can browse by topic. +- Keep scope and limitations highly visible to reduce expectation mismatch. +- Only commit documentation files in the wiki repo and gitlink metadata in the main repo. + +## Implementation Units + +### U1: Branch and Submodule Setup + +Goal: + +- Create a dedicated feature branch from `main`. +- Add `wiki/` submodule targeting the repository's wiki remote. + +Verification: + +- `.gitmodules` contains a `wiki` entry with the correct URL. +- `git submodule status` shows a pinned commit for `wiki`. + +### U2: Create Non-Technical Wiki Structure + +Goal: + +- Build a discoverable set of wiki pages for end users. + +Planned pages: + +- `Home.md` +- `What-TalkEd-Is.md` +- `Getting-Started.md` +- `Editing-Workflow.md` +- `Import-Export-And-File-Safety.md` +- `Limitations-And-Scope.md` +- `Troubleshooting.md` +- `FAQ.md` +- `Glossary.md` + +Verification: + +- All pages exist in `wiki/` and are linked from `Home.md`. +- Writing avoids deep technical assumptions. + +### U3: Validation and Publication + +Goal: + +- Validate docs quality and persist all required commits. + +Verification: + +- Main repo status clean after commit/push. +- Wiki submodule commit pushed to wiki remote. +- Main repo commit references updated submodule pointer and `.gitmodules`. + +## Risks + +- Submodule add can fail if authentication for wiki remote is not available. +- Incomplete page linking can create dead-end navigation for non-technical users. +- Ambiguous wording can overpromise unsupported app capabilities. + +## Deferred To Implementation + +- Exact sentence-level copy polish for each page. +- Final ordering of top-level links on `Home.md` after drafting all pages. diff --git a/wiki b/wiki new file mode 160000 index 0000000..2a921f1 --- /dev/null +++ b/wiki @@ -0,0 +1 @@ +Subproject commit 2a921f1552fba9d7ccd270ef3c6c27c5eb706094