digdir
Cross-agency group to explore multi-platform documentation distribution
We need to initiate a cross-agency working group to explore how we can distribute documentation across multiple solutions. The goal is to establish a technical approach that allows for shared content while accommodating the few cases where differences are required.
For example:
- A pattern description might be identical across platforms, but example images could differ.
- Some teams might want to keep the text consistent while customizing visual examples.
Discussion points:
- Advantages and disadvantages of using GitHub as the primary source of documentation.
- To what extent it is technically feasible to distribute content in smaller chunks versus as a complete package.
Outcome: A recommendation for a distribution strategy, including technical feasibility, tooling, and potential maintenance implications.
Happy to take this and come back with an initial draft.
The draft will cover:
- A recommended distribution strategy (shared text + platform-specific images/examples)
- Pros/cons of using GitHub as the primary source
- Distribution in smaller chunks vs. a complete package
- Technical feasibility, tooling, and maintenance implications
- A small pilot proposal (one pattern page) to validate the approach
Please let me know if there are any constraints you want me to consider, and feel free to assign me.
Thanks a lot for showing interest @RamtinMoshtagh 🙌 We really appreciate that you want to contribute!
This specific task is intended for the internal cross-agency team, and a discussion between Digdir, Nav, Skatteetaten, Brreg, Udir, Mattilsynet whether shared documentation makes sense for us. We’ll start with a working session to weigh the pros and cons of having parts of the documentation shared. If the group decides shared docs is the way to go, there might be room for contributions.
Møte 29.08.2025
Representanter fra Mattilsynet, Digdir, Skattetaten, Nav og UDIR
Oppsummering
Det er for tidlig å begynne å diskutere tekniske løsninger. Vi har ikke oversikt over hvilken type dokumentasjon som kan være relevant å dele på tvers. Det første vi må finne ut er hva gir mening å dele på tvers. Her det vi diskuterte som relevant.
- mønster
- god praksis (disabled states, hvordan sette opp filter?)
- burde deler av komponentdokumentasjonen skilles ut
Veien videre blir å se på dokumentasjonsstrukturen og sette opp et møte med de som er interessert i å diskutere dette. Vi kan forberede i forveien så vi har konkrete eksempler vi kan diskutere.
Andre innspill / behov
- Vi ønsker ikke eksportere alle mulighetene som er i Designsystemet til brukerne. Vi trenger derfor kun dokumentasjon for de delene vi bruker.
- Å ha en dokumentasjon man kan ta i bruk som utgangspunkt når man setter opp sin egen versjon av designsystemet kunne vært nyttig for å komme raskt i gang
- Vi ser at vi får mange eksempler, caser og dokumentasjon som er unikt for oss. Det blir vanskelig å bruke Digdirs dokumentasjon da.
- Det er ikke galt å bruke lenker. Man kan lenke til mønster der det er relevant i vår dokumentasjon. Det må ikke leve to steder.
- Oppfølging: Det er mye av det som står i mønsterene som allerede er innebygd i komponentene våre. Det blir mye unødvendig informasjon
- Vi vil også gjerne vise mønster dokumentasjonen i kontekst som passer bedre for oss. Hvordan vi løser dette mønsteret i vår organisasjon. Med relevante mønster.
- File watcher ble spilt inn som en mulig løsning, hvor man kan få e-post varsler når det skjer endringer på spesifikke filer i et repo.
- Vi diskuterte også om "retningslinjer/når skal jeg bruke denne" type dokumentasjon, kanskje burde trekkes ut av komponentdokumentasjonen. I hvilken situasjoner skal jeg bruke tabs vs togglegroup kunne vært en egen artikkel for eksempel. I stedet for at brukere må orientere seg rundt i dokumentasjonen.
