fiskaltrust / fiskaltrust/docs

Epic: fold the knowledge base articles into the documentation

Open
#105 3 comments 0 reactions 0 assignees View on GitHub
category-docs category-technical-debt
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.