This is an automated email from the ASF dual-hosted git repository.
spmallette pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
The following commit(s) were added to refs/heads/master by this push:
new ae09b59368 Clarify that IO documentation is specification-only
ae09b59368 is described below
commit ae09b59368c4b2de8a890bfa99fd20035b4f81c8
Author: Stephen Mallette <[email protected]>
AuthorDate: Thu Sep 24 20:01:48 2026 +0000
Clarify that IO documentation is specification-only
The IO book documents the serialization formats for providers and advanced
users implementing against them. Make explicit in books-and-voice.md that
these files specify the wire and file format rather than teach how to read
or
write it in code, so examples that invoke a reader or writer belong in the
reference and tutorial books instead. The existing guidance that
format-illustrative snippets are appropriate is preserved.
Assisted-by: Kiro:claude-opus-4.8
---
.skills/tinker-doc/references/books-and-voice.md | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/.skills/tinker-doc/references/books-and-voice.md
b/.skills/tinker-doc/references/books-and-voice.md
index 3548c0994b..2d4d8b394f 100644
--- a/.skills/tinker-doc/references/books-and-voice.md
+++ b/.skills/tinker-doc/references/books-and-voice.md
@@ -348,6 +348,13 @@ exactly. Match the structure already used for the format
being edited rather tha
reorganizing it, and keep examples illustrative (`[source,text]` or
`[source,json]`) rather than executable.
+An IO document is a specification, not a place to learn Gremlin or how to use
+TinkerPop. Its examples illustrate the shape of the serialized data itself with
+`[source,text]` or `[source,json]` snippets that are never executed, and it
does
+not show how to invoke a reader, writer, or the `io()`-step in code, as that
+belongs in the reference or tutorial books. That a reader cannot produce or
+consume data from an IO section alone is by design, not a documentation gap.
+
---
## Future Documentation
