Affects Version/s: None
Fix Version/s: None
Component/s: acumos-hippo-cms, acumos-nexus-client, acumos-python-client, common-dataservice, databroker, documentation, federation, generic-model-runner, message-handling, microservice-generation, model-schema, modeling-toolkit, platform-oam, proto-viewer, python-dcae-model-runner, runtime-orchestrator, system-integration, test-automation, training
Project-level docs should be reviewed and updated:
- consistent versioning – version 1.0.0 vs v1
- consistent date format
- each should contain links to the Jira tickets in addition to the ticket summary
- this should be very technical, aimed at people who want to help develop the components
- this should be how the component does what it does, not a requirements document of what the component should do
- include an Architecture and Design section with diagrams and explanations!
- this should contain what language(s) and frameworks are used, with versions
- this should contain how to obtain the code, where to look at work items (Jira tickets), how to get started developing
- user-guide.rst (if needed)
- if the guide contains sections on third-party tools, is it clearly stated why the Acumos platform is using those tools? are there instructions on how to install and configure each tool/toolset?
- does the guide state who the target users are? for example, modeler/data scientist, Acumos platform admin, marketplace user, design studio end user, etc
- if there are instructions, they are clear, correct, and fit for purpose
does the guide contain information more suited for a different guide?
- a user guide should be how to use the component or system; it should not be a requirements document
- API docs - you can generate documentation from a swagger json file
- tutorials (if needed)
- https://docs.acumos.org/en/latest/docs-contributor-guide/index.html which has been updated with new sections on writing component-level documentation and reviewing RST in Gerrit