Skip to content

[DOCS]: README rationalization #2365

@jonpspri

Description

@jonpspri

📚 Documentation Issue Summary

The README has become overwhelmingly long and complex, and seemingly redundant
with materials also in the formal documentation. This issue will track
suggestions and approaches to simplifying the README.

It is acknowledged that given the pending refactoring from a monorepo into
several smaller repositories, portions of the README will be refactored as well.

Therefore the suggestion is addressing this issue be "blocked" by the monorepo
refactoring and addressed after the current repo contents are stable.

💡 Suggested Fix or Clarification (optional)

Refer to web resources on best practices for project READMEs. Keep it simple and
relevant to the technical user who is likely to access the Python Package or
GitHub repository.

  • Early in the readme should be Directions to the current documentation.

  • Information on how to obtain the latest container image(s)

  • Information on how to obtain the latest Python package

  • A simple, ACCURATE "getting started" scenario.

  • Links directly to the "How To" and "Getting Started" sections of the manual.

  • A quick-start on setting up to contribute with a link to more in-depth guidelines.

More suggestions welcome in issue commentary while we wait to start the work.

Metadata

Metadata

Assignees

Labels

COULDP3: Nice-to-have features with minimal impact if left out; included if time permitsdocumentationImprovements or additions to documentationfixedIssue has been resolvedmarkdownDocumentation (mkdocs / markdown)

Type

Projects

No projects

Relationships

None yet

Development

No branches or pull requests

Issue actions