List of documentation problems

This is a special issue for collecting minor errors, conflicts, inconsistencies etc. in the documentation that may not have merit to become their own issue/task. The errors, since small, can be fixed as part of other tasks.

After fixing an item on the list, check the checkbox and add the PR number of the change containing the fix after the item title/description.

Not done ( to be completed independently )

• #1048
• #1049
• #1050

Fixed Problems

• Registering bundles #995
  • Missing step: porter build needs to be run before running publish_register_bundle.sh script
  • The API for registering bundles is different than what is shown in the docs
  • Several typos/grammar mistakes
• JSON schema for base workspace creation is wrong (see Guy’s comment below) #995
• Swagger UI screenshot for /api/workspace-template is not up to date (see Guy’s comment below) #995
• Guacamole image tag environment variable is missing in the docs at Guacamole workspace-service (see Guy’s comment below) #995
• Example of a fixed item #370
• Consider moving all TRE Developer centric docs into the source tree (away from /docs), for example testing.md.
• E2E tests .env.sample contains SCOPE, but the variable is not documented in testing.md #844
• E2E app registration API permissions need to have Granted for [directory name] status, which is not documented in auth.md #844
• deployment-quickstart.md and manual-deployment.md contain way too much duplicate information - this will result in outdated, confusing and possibly conflicting documentation
• E2E tests README lacks prerequisites
• Remove logical-data-model from docs folder
• Remove Index.md and move repo structure to the readme.md in the root
• Move API and resource processor from Azure TRE Overview/composition service to TRE Developers
• Do a pass through the docs for a readability and consistency - what do we mark as ticks, what do we mark as bold, what is uppercase etc.
• Remove the Developer Guide - everything is covered elsewhere
• Rename Development Environment to Developer Guide
• Change hcl to terraform everywhere in code quotes for proper code highlighting (ex. firewall rules)
• Paths in InnerEye workspace service docs’ build and install step are wrong: should be ./templates/workspace_services/innereye, not ./templates/workspace_services/innereye_deeplearning #989
• The redirect URLs (2 in auth.md and 1 in pre-deployment-steps.md) all differ and none of them look correct
• Setup Instructions - Installing Base Workspace: #989
  • The first command register-bundle DIR=./templates/workspaces/base is wrong
  • The Swagger UI URL is wrong
• Internal links from workspace/workspace services broken e.g., prerequisites link at https://microsoft.github.io/AzureTRE/tre-templates/workspace-services/inner-eye/ #989
• Auth docs should explain what “admin consent” is and what it means #989

[guybartal]

GUACAMOLE_IMAGE_TAG is missing in the docs: https://github.com/microsoft/AzureTRE/blob/develop/docs/tre-templates/workspace-services/guacamole.md

[guybartal]

screenshot for /api/workspace-template swagger ui is not up to date, it should be “Register Workspace Template” and not “Create Workspace Template”