Documentation Standards

TinkerPop relies heavily on the individual project wikis for it’s technical and user documentation. The following items represent some general guidelines to follow when making changes to those wikis:

• All wiki pages use Textile formatting. Before making changes or adding new pages, examine the formatting in other pages and replicate that formatting as necessary.
• All images are PNG’s with transparent backgrounds.
• If you use OmniGraffle and the image is complex, save the original .graffle file as a “flat file” (else Git and Windows breaks).
• Use the naming conventions of this-is-a-name.png (not this_is_a_name.png).
• All examples (where it makes sense) should be in terms of the TinkerPop toy graph.
  • Not, marko—knows—>josh, and then in the next example, garfield—is—>cat.
  • If possible, build up your example as “running code” (the current code builds on the previous code).
  • While the “toy graph” should be the common starting point for examples, divergence from this graph is acceptable if it is insufficient to express an important point.
• Try and keep each page of documentation to a “single printed page.”
  • If its too big, consider breaking it out into another page.
  • Think about the outline of the documentation (the sections, subsections, etc.)
• If possible, the code examples in any page should be standalone which allows the reader to cut and paste working code.
• Avoid “I” “you” and “we” (just my style when I write :).
• Anytime there is a Java class name or inline code, use MyClass.