Skip to content

Best practices

Best Practices

This folder is guidance, not conformance. Nothing here is a MUST/SHOULD/MAY requirement — those live in specs/portolan/. These are discussion pieces and recommendations on how to build good Portolan catalogs, aimed at both the people who publish them and the agents that consume them.

Contents

  • documentation.md — what belongs in your AGENTS.md and what makes a good README.md.
  • philosophy.md — how to think about scoping, organizing, and maintaining a Portolan catalog; pointers to exemplary catalogs.
  • git-backed-catalogs.md — keeping catalog metadata in a repository, with the data outside it, and validating every change in CI.
  • multilingual-catalogs.md — how to publish and maintain catalog metadata in several languages.
  • grader.md — the rubric for rating catalog quality, A+ through F.
  • styling.md — making visualization styles that are clear and distinctive across a catalog.
  • conversion-defaults.md — the COG, partition, and thumbnail settings the Portolan CLI uses when converting source data.