Dokumentasjon 🧠

Konseptet for dokumentasjon av Utviklerportalen (https://utviklerportal.nhn.no) er å bruke markdown‑filer for å forklare hvordan endepunktene brukes. For det grunnleggende kan du benytte swagger‑ (open api)‑endepunktene, men når du trenger å utdype, er markdown‑filene et godt valg.

DX (Developer Experience 👍) har vært en viktig betraktning, slik at alt holdes så enkelt som mulig. Dokumentasjonen er et Git‑repo som kan klones og pushes akkurat som ethvert annet kode‑repo. Når filene er pushet til Milliways‑Git‑repoet, synkroniseres de automatisk til Utviklerportalen.

Hvert team får et eget område hvor dokumentasjonen ligger på https://milliways.nhn.no/samhandlingsplattform.

Legge til et docs‑repo 📁

Du må først ha et repository på Milliways. Hvis du ikke har tilgang, ta kontakt med noen i Slack‑gruppen #nhn-dhp-utviklerportal for å få tilgang, så vil en ny gruppe bli opprettet. Der oppretter du en ny Subgroup. Navnet du velger for sub‑gruppen vil være synlig i Utviklerportalen, så velg et navn som gir mening. For at katalogen skal finne dokumentene, er det noen krav:

• Grenen må hete main. Merk at Milliways som standard kan opprette master ved opprettelse av nye repoer.
• Det må finnes én katalog som heter docs. docs‑mappen må ligge i rot‑nivået i repoet.
• Det må finnes en fil som heter metadata.json i docs‑mappen.

Merk at mapper kan ligge under docs‑mappen, og det er ingen maksimal dybde på mappestrukturen. Lesbarheten kan imidlertid bli dårligere med mange undermapper. Hvert team klarer seg vanligvis med én eller to nivåer av mapper.

Lage en ny tjeneste i backoffice 🗂️

Når du har tilgang til backoffice i Umbraco, kan du legge til en ny tjeneste. Dette gjøres i Innhold‑delen ved å høyreklikke på «Informasjonstjenester» og velge «Side».

En annen måte er å bruke malen for en ny tjeneste.

Derfra kan du legge til produkter osv. Vi har lagt inn innsats for å gjøre backoffice‑opplevelsen brukervennlig, så forhåpentligvis er prosessen intuitiv.

Hvordan katalogen henter informasjon fra Milliways 🔧

Katalogen ser på alt under gruppe‑ID 264 («Samhandlingsplattformen») og henter alle prosjektene som finnes der. I tillegg finner den prosjekter som har en /docs‑katalog og en metadata.json‑fil i eller ved siden av /docs‑katalogen. Merk at på grunn av hvordan Git fungerer, vil /docs‑katalogen ikke bli oppdaget hvis den er helt tom. Det anbefales derfor å ha metadata.json på samme nivå som /docs‑katalogen.

Automatisk synk og katalogen ⚡

Synkroniseringen fra Milliways til https://utviklerportal.nhn.no/ trigges av webhooks. Når du har gjort en commit og pushet til Milliways, er det kun noen sekunders forsinkelse fra du har committet filen til den blir oppdatert på Utviklerportalen. I tillegg til webhooken kjører en time‑basert jobb som sørger for at all data har blitt oppdatert.

Mappestruktur

Synk støtter at filene ligger i en mappestruktur. I prinsippet kan du ha uendelig dybde på mapper. Strukturen replikkeres dynamisk når API‑siden rendres. Mappestrukturen du har i Git‑repoet, vil vises på venstre side i portalen.

metadata.json‑filen 📈

metadata.json‑filen spiller en viktig rolle ved synk fra Milliways til Utviklerportalen. Den finnes på samme nivå som docs‑katalogen.

Tips for å lage god dokumentasjon 🦄

Når du dokumenterer funksjoner, trenger du ofte å legge til bilder. Utviklerportalen har støtte for dette. Det er beskrevet her. Du kan også referere til andre filer i dokumentasjonen din.

En markdown‑fil kan pyntes med front matter i starten av filen, noe som påvirker flere muligheter for den enkelte fil.

Du kan også legge til noen design‑komponenter for å tilpasse markdownen mer til Utviklerportalens design. For link‑bokser, link‑knapper og dropdown‑menyer (akordioner) se her. Du kan også legge til fanetabeller med kodeeksempler i markdown. For ankre, se her.

Til slutt, noen tips for å friske opp markdownen din!

Andre funksjoner 👀

Utviklerportalen har spesiell støtte for å render roadmaps og release notes.