fiskaltrust / fiskaltrust/docs
Epic: fold the knowledge base articles into the documentation
- Dominant language
- MDX
- Stars
- 0
- Forks
- 0
- Avg merge
- 5d 15h
- Merged PRs (30d)
- 18
Description
## Context
Knowledge base articles (KBA) live in Dynamics 365, outside this repository. That has cost us:
- **They go stale silently.** There is no review cycle and no link to the product. Articles still describe Windows XP, WSDL, Mono 6.8 and `fiskaltrust.Service` v1.x.
- **They are hard to maintain.** No version control, no review, no CI, no link checking. Content is authored in a CRM rich-text editor and stored as HTML blobs.
- **They duplicate the docs, and each other.** The same topic exists as an EN article and an FR article that have since drifted apart, and as a section of a docs page that says something different.
- **They are invisible.** They are only reachable from the Help section of the fiskaltrust.Portal, so they do not benefit from search, sitemaps or the docs navigation.
The KBAs are therefore being phased out. This epic tracks folding their content into the public documentation, market by market.
## Target model
Two content types, with a strict rule about which one owns knowledge:
**Docs carry the knowledge.** General and market-specific knowledge and context belong in the documentation — in the page that owns the topic, with market-specific detail in the corresponding `_markets//…` partial.
**FAQ presents the knowledge for a specific pain point.** An FAQ entry frames a question a reader actually asks and points at the answer. It must **not** be the only place a fact lives. If an FAQ entry would introduce knowledge or context that is not in the docs, that content goes into the docs first, and the FAQ entry then references it.
The practical consequence: no KBA is ever "migrated to the FAQ" as a way of avoiding the work of placing its content properly.
## Approach per market
Each market is handled in its own sub-issue, following the same steps:
1. **Extract** the market's `dbo.kbarticle` and `dbo.knowledgearticle` tables, deduplicate versions, and strip the HTML.
2. **Categorise** every article:
- `MERGE` — real content with no equivalent in the repo; folds into the page that owns the topic.
- `FAQ` — already covered by the docs, worth surfacing as a question against the existing page.
- `PROCESS` — a detailed process workflow; captured, but handled separately.
- `DUP` — an EN/FR pair or a near-identical sibling; collapsed.
- `DROP` — empty, internal, or without a usable resolution; listed for the record and discarded.
3. **Map** each surviving article to a concrete target file, verified to exist.
4. **Write** the content, in English, in the voice of the surrounding page.
5. **Flag** every claim the repo can neither confirm nor contradict, for a human to verify. The repo is the source of truth in a conflict, but silence is not a conflict.
6. **Remove the dependencies on the KB**, so the docs stop pointing at a feature that is going away.
## Conflict rule
Where a KBA and this repository disagree, **the repository wins**. Most KBAs are older than the pages that now cover the same ground.
## Cross-cutting work
Independent of any single market, the documentation currently points readers at the KB and must be reworked before it is switched off:
- [ ] `posdealers/information-sources/knowledge-base.md` — an entire page teaching readers to use the Portal's KB feature, with screenshots.
- [ ] `posdealers/technical-operations/troubleshooting/troubleshooting-guide.md` — step 1 of the recommended troubleshooting order is "read the KBA and the FAQ".
- [ ] The per-market `_trouble.mdx` partials, which link to `portal.fiskaltrust./KBArticle`.
- [ ] Decide where FAQ content lives, and whether the existing top-level `faq/` section (currently `roles.md` and `terms.md`) is the right home.
## Markets
One sub-issue per market. Exports currently exist for AT, DE and FR; further markets get a sub-issue as their export lands.
France runs first, as a pilot — the point is to validate the categorisation, the target model and the placement rules on a real export before the other markets are processed.
Contributor guide
Research direction
Start with posdealers/information-sources/knowledge-base.md and posdealers/technical-operations/troubleshooting/troubleshooting-guide.md, then inspect the per-market _trouble.mdx partials. Review the France pilot sub-issue and its export before changing shared documentation. Done means the documented KB dependencies are removed or replaced, surviving content has verified target files, and unresolved claims are flagged for human review.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100