Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitmodules
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
[submodule "wiki"]
path = wiki
url = https://github.com/OpenKotOR/TalkEd.wiki.git
2 changes: 1 addition & 1 deletion docs/plans/2026-05-27-repo-hardening-plan.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: TalkEd Repo Hardening Plan
date: 2026-05-27
status: active
status: completed
---

## Overview
Expand Down
94 changes: 94 additions & 0 deletions docs/plans/2026-05-27-wiki-submodule-docs-plan.md
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions wiki
Submodule wiki added at 2a921f
Loading