Central documentation about crucial changes and decisions

[krvoigt]

Current situation Currently it is not clear to team where to provide documentation about crucial changes and decisions. Example:

• we decided to use Nextflow as a workflow engine, and the whole .nf file (Nextflow file) as the workflow format
• workflow server and processing server including web API implementation is part of the impl projects. OCR-D Koord provides the Web API spec. Only the REST API wrapper of a single processor is provided by OCR-D Core.

There were several suggestions where to document like the following:

• description of the main epics (epic column) in the board
• documentation in the dariah Wiki
• documentation in the github wiki
• information should be provided in the changelog

User Story As a developer and technical user, I would like to have an overview of the current architecture and documentation of key architectural decisions so that I have a better understanding of the architecture and how I can implement OCR-D.

Steps

• [x] define what information is not documented yet
• [x] define where to document -> spec
• [x] define how to document -> see comment
• [x] provide draft for documentation in spec

Acceptance Criteria

• [x] There is a place for documentation
• [x] the place is communicated to the team

Prior Art WIP Pad: https://pad.gwdg.de/KRhbnDIbQUikojfPmpaM-g?both

[mweidling]

I think we might need a meeting for this; Or at least a place for discussion. Maybe here?

[krvoigt]

pad: https://pad.gwdg.de/KRhbnDIbQUikojfPmpaM-g

[krvoigt]

Meeting results:

• decisions to be announced in the decisions document are collected at the end of the sprint (what should others know as well? why did we make this decision?)
• put workflow + benchmarking + decision info under /spec decision document should contain all decisions (e.g. architecture) we make
• new decision in the decisions document will be announced in gitter here goes everything that is of interest to others, sorted by topic and then chronologically Example: “We decided to go for NextFlow as workflow engine because XYZ. The detailled discussion can be viewed at Zenhub [link].”

[krvoigt]

Information that is currently missing:

• we decided to use Nextflow as a workflow engine, and the whole .nf file (Nextflow file) as the workflow format workflow server and processing server including web API implementation is part of the impl projects (Mehmet, Triet)
• OCR-D Koord provides the Web API spec. Only the REST API wrapper of a single processor is provided by OCR-D Core. (Jonas, Triet)
• Changes/Upgrades to our tech stack:
  • supported python versions
  • linux base image
  • additional libraries/software (MongoDB, uvicorn...) (
• Switch to Slim Containers in ocrd_all (Konstantin)
• Python API changes (Konstantin)