sul-dlss / cocina-models

Cocina repository data model (implemented in Ruby)
https://sul-dlss.github.io/cocina-models/
3 stars 0 forks source link

Design updates for descriptive type documentation #415

Closed arcadiafalcone closed 2 years ago

arcadiafalcone commented 2 years ago

The Markdown version of documentation at https://github.com/sul-dlss/cocina-models/blob/main/docs/description_types.md is closer to the desired display than the HTML version at https://sul-dlss.github.io/cocina-models/description_types.html, so the latter is not necessary.

  1. The description should be on the line after the type term, with an indented bullet point.
  2. Keep camelCase in headers.
  3. If a type term has a status and/or use attribute, put it in an indented bullet point after the description (if present) in this form: Deprecated. Preferred usage: #{value of use attribute}.. Not all deprecated values will have a use attribute.
  4. Add .type to the end of each path.
  5. Don't include "Description types" as the top level header.
  6. The header size should go down one each time a part is added to the path. So "Contributor types" (contributor.type) would be header 1, "Contributor name types" (contributor.name.type) would be header 2, and "Contributor name part types for structuredValue" (contributor.name.structuredValue.type) would be header 3.

See https://github.com/sul-dlss/cocina-models/blob/desc-documentation-sample/docs/descMD/documentation_test.md for an example of the desired formatting.

arcadiafalcone commented 2 years ago

Builds on #396