The current schema document is primarily a reference manual for the naming conventions, facts, and edges defined by the Kythe graph. For authors of new indexers, it would be helpful to have an informal survey/orientation document for the schema. Some topics I think would be useful to gather together include:
- Naming conventions (tickets and VNames, how to ensure uniqueness using examples like files, anchors, built-in types).
- How Kythe maps a graph of nodes and edges to entry tuples (node = facts, edge = nodes + label).
- A high-level tour of some of the common graph structures: File info, definition/usage cross-reference, call-graph, maybe a simple type structure.
It's an open question whether this should be part of the existing schema, or a separate document. The reference component of the schema should remain the source of truth, but an informal survey would I think help people figure out which pieces of the schema they need to care about—and why.