Ga naar hoofdinhoud

Software Guidebook (SGB)

Voor de documentatie gebruik je het Software Guidebook van Simon Brown als uitgangspunt.

Maar je kunt ook de Reader gebruiken die we beschikbaar stellen.

De resultaten van de onderzoeken verwerk je in een Software Guidebook​

Zorg dat jullie Software Guidebook in ieder geval de volgende hoofdstukken bevat.

  1. Context
  2. Functional Overview
  3. Quality Attributes
  4. Constraints
  5. Principles
  6. Software Architecture
  7. Code
  8. Data
  9. Infrastructure Architecture
  10. Deployment
  11. Operation and Support
  12. Development Environment
  13. Decision Log

Software Guidebook

Daarnaast is er waarschijnlijk nog andere documentatie met onderzoeken en onderzoeksresultaten. Deze documentatie kun je integreren in het software guidebook, maar je kunt ook linken naar specifieke plekken in jullie repo als dat handiger is.

GitHub Pages​

In het vak SoEx heb je een voorbeeld gezien van een Software Guidebook geschreven in MarkDown in een GitHub repo. In dit project vragen we van jullie om het Software Guidebook in GitHub Pages te publiceren.

Zie https://pages.github.com/ voor een introductie in publiceren op github pages.

Voor het toevoegen van basis-styling kun je het beste een static site generator gebruiken. GitHub raadt zelf Jekyll aan. Zie:

Populaire alternatieven zijn:

Aanbevolen: Docusaurus​

Docusaurus als documentatieplatform

Wij adviseren in PEXE om Docusaurus te gebruiken voor het Software Guidebook.

Waarom dit praktisch is voor dit project:

  • Navigatie en structuur voor hoofdstukken zoals Context, Architecture en Decision Log.
  • Zoeken over alle pagina's (via plugin).
  • Goed te combineren met C4 en UML diagrammen en voorbeelden in Markdown/MDX.
  • Makkelijk te publiceren via GitHub Pages met GitHub Actions pipeline (bekend uit PWAC project).

Diagrammen met remark-kroki-a11y​

Als je in je SGB veel domeinmodellen, C4-diagrammen en user story map visualisaties hebt, voeg dan remark-kroki-a11y toe:

  • Het helpt blinde en slechtziende lezers via toegankelijke beschrijvingen
  • Het helpt ook bij situationele disabilities: bijvoorbeeld opdrachtgevers of domeinexperts die een klassendiagram niet kunnen of niet willen lezen, maar wel snel een begrijpelijke uitleg nodig hebben

Check uitklapbalk voor achtergronden en how-to's.

Achtergrond/how to en voorbeeld (uitklappen)

Kroki is een verzameltool voor allerlei text-to-diagrans tools, zoals PlantUML, Mermaid en C4. Kroki...

"provides a unified API with support for BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag), BPMN, Bytefield, C4 (with PlantUML), D2, DBML, Ditaa, Erd, Excalidraw, GraphViz, Mermaid, Nomnoml, Pikchr, PlantUML, Structurizr, SvgBob, Symbolator, TikZ, UMLet, Vega, Vega-Lite, WaveDrom, WireViz... and more to come!" — kroki.io

Remark is:

"an ecosystem of plugins that work with markdown as structured data, specifically ASTs (abstract syntax trees). ASTs make it easy for programs to deal with markdown. We call those programs plugins. Plugins inspect and change trees. You can use the many existing plugins or you can make your own." — remark

En Markdown is:

"a simple way to format text that looks great on any device. It doesn’t do anything fancy like change the font size, color, or type — just the essentials, using keyboard symbols you already know." — commonmark.com

Voorbeelden markdown syntax:

# Heading 1 -> # Heading 1

  • *Italic* -> Italic
  • **Bold** -> Bold
  • [Linktekst voor website a](http://a.com) -> Linktekst voor website a ⋮ De installatie- en configuratiestappen staan hier.

Werkt dit ook met Jekyll of MkDocs?​

In principe zou de plugin daar ook moeten werken omdat de plremark (en deze plugin) draait. Omdat remark-kroki-a11y een remark-plugin is, is de techniek niet strikt Docusaurus-specifiek. De standaard Jekyll- en MkDocs-pipelines draaien dit niet automatisch, dus je hebt daar extra integratie of een pre-build stap nodig. Voor dit vak is Docusaurus daarom waarschijnlijk de snelste route.

Voorbeeld domein model​

Voorbeeld met For devs / Simpler toggle op een domeinmodel:

c9c09ec45584be54f2043796b1b7e123

PlantUML broncode voor "Meta-domainmodel Domain Storytelling"
@startuml
hide circle

class Team {
  +teamId: UUID
  +naam: String
  +sprintNummer: int
  +elicitDomainStory(expert: DomeinExpert, domain: Domain): DomainStory
  +verifyDomainStory(story: DomainStory, expert: DomeinExpert): boolean
  +adjustDomainStory(story: DomainStory, feedback: String): void
}

class DomeinExpert {
  +expertId: UUID
  +naam: String
  +rol: String
  +verteltDomainStory(domain: Domain): DomainStory
  +bevestigtVisualisatie(story: DomainStory): boolean
}

class Domain {
  +domainId: UUID
  +naam: String
  +beschrijving: String
  +heeftUbiquitousLanguage(): UbiquitousLanguage
}

class UbiquitousLanguage {
  +versie: String
  +termen: List<String>
  +voegTermToe(term: String): void
  +normaliseerTermen(): void
}

class DomainStory {
  +storyId: UUID
  +titel: String
  +context: String
  +status: StoryStatus
  +visualiseer(): String
  +valideerOpTerminologie(ul: UbiquitousLanguage): boolean
}

class Activiteit {
  +activiteitId: UUID
  +werkwoord: String
  +volgorde: int
}

class Actor {
  +actorId: UUID
  +naam: String
  +type: ActorType
}

class WorkObject {
  +objectId: UUID
  +naam: String
  +state: String
}

enum StoryStatus {
  Draft
  Gevalideerd
  Aangepast
}

enum ActorType {
  Human
  System
}

Team --> DomeinExpert : "elicit bij"
DomeinExpert --> DomainStory : "vertelt"
Team --> DomainStory : "verifieert + past aan"
DomainStory --> DomeinExpert : "gevalideerd door"

Domain "1" --> "0..*" DomainStory : hoort bij
Domain "1" *-- "1" UbiquitousLanguage : gebruikt
DomainStory "1" *-- "1..*" Activiteit
DomainStory "1" *-- "1..*" Actor
DomainStory "1" *-- "1..*" WorkObject
@enduml

Klassendiagram met 8 klasse(n) en 9 relatie(s).

Klassen:

  • Klasse Team met:
    • publieke methode 'elicitDomainStory', met parameter(s) 'expert' van type DomeinExpert, 'domain' van type Domain, return type DomainStory
    • publieke methode 'verifyDomainStory', met parameter(s) 'story' van type DomainStory, 'expert' van type DomeinExpert, return type boolean
    • publieke methode 'adjustDomainStory', met parameter(s) 'story' van type DomainStory, 'feedback' van type String, return type void
    • publieke attribuut 'teamId' van type UUID
    • publieke attribuut 'naam' van type String
    • publieke attribuut 'sprintNummer' van type int
  • Klasse DomeinExpert met:
    • publieke methode 'verteltDomainStory', met parameter(s) 'domain' van type Domain, return type DomainStory
    • publieke methode 'bevestigtVisualisatie', met parameter(s) 'story' van type DomainStory, return type boolean
    • publieke attribuut 'expertId' van type UUID
    • publieke attribuut 'naam' van type String
    • publieke attribuut 'rol' van type String
  • Klasse Domain met:
    • publieke methode 'heeftUbiquitousLanguage', zonder parameters, return type UbiquitousLanguage
    • publieke attribuut 'domainId' van type UUID
    • publieke attribuut 'naam' van type String
    • publieke attribuut 'beschrijving' van type String
  • Klasse UbiquitousLanguage met:
    • publieke methode 'voegTermToe', met parameter(s) 'term' van type String, return type void
    • publieke methode 'normaliseerTermen', zonder parameters, return type void
    • publieke attribuut 'versie' van type String
    • publieke attribuut 'termen' van type List van String
  • Klasse DomainStory met:
    • publieke methode 'visualiseer', zonder parameters, return type String
    • publieke methode 'valideerOpTerminologie', met parameter(s) 'ul' van type UbiquitousLanguage, return type boolean
    • publieke attribuut 'storyId' van type UUID
    • publieke attribuut 'titel' van type String
    • publieke attribuut 'context' van type String
    • publieke attribuut 'status' van type StoryStatus
  • Klasse Activiteit met:
    • publieke attribuut 'activiteitId' van type UUID
    • publieke attribuut 'werkwoord' van type String
    • publieke attribuut 'volgorde' van type int
    • geen methoden
  • Klasse Actor met:
    • publieke attribuut 'actorId' van type UUID
    • publieke attribuut 'naam' van type String
    • publieke attribuut 'type' van type ActorType
    • geen methoden
  • Klasse WorkObject met:
    • publieke attribuut 'objectId' van type UUID
    • publieke attribuut 'naam' van type String
    • publieke attribuut 'state' van type String
    • geen methoden

Relaties:

  • Team heeft een associatie-relatie met naam '"elicit bij"' met DomeinExpert
  • DomeinExpert heeft een associatie-relatie met naam '"vertelt"' met DomainStory
  • Team heeft een associatie-relatie met naam '"verifieert + past aan"' met DomainStory
  • DomainStory heeft een associatie-relatie met naam '"gevalideerd door"' met DomeinExpert
  • Domain heeft een associatie-relatie met naam 'hoort bij' met DomainStory, multipliciteit 1 naar 0..*
  • Domain heeft een compositie-relatie met naam 'gebruikt' met UbiquitousLanguage, multipliciteit 1 naar 1
  • DomainStory heeft een compositie-relatie met Activiteit, multipliciteit 1 naar 1..*
  • DomainStory heeft een compositie-relatie met Actor, multipliciteit 1 naar 1..*
  • DomainStory heeft een compositie-relatie met WorkObject, multipliciteit 1 naar 1..*

701e4b8e1567bdacd1573e6de7244ccd