[RFC] TVM Documentation Refactor

Introduction

A major component of building a community is making it easy for new contributors to become successful with the project, while giving clear reference materials for experienced contributors to build upon and use existing work.

A strong documentation system should support the entire lifecycle of a community member. This RFC proposes a refactoring of TVM documentation to better support the entire community. Based on the system developed by Divio, this refactoring will focus on creating four major categories of documentation:

  • Introductory Tutorials: Practical documents that are most helpful in helping new users learn the software.
  • How-to Guides: Practical documents that are most helpful in getting work done.
  • References: Advanced documents that are most helpful in getting work done
  • Deep Dives: Advanced documents that are most helpful in learning they why’s of the software.

The Four Document Types

Introductory Tutorials

These are step by step guides to introduce new users to a project. A successful introductory tutorial successfully get the user engaged with the software without necessarily explaining why the software works the way it does. Those explanations can be saved for other document types; the introductory tutorial focuses on a successful first experience. These are the most important docs to turning newcomers into new users and developers. A fully end-to-end tutorial, from installing TVM and supporting ML software, to creating and training a model, to compiling to different architectures will give a new user the opportunity to use TVM in the most efficient way possible.

Tutorials need to be repeatable and reliable, because the lack of success means a user will look for other solutions.

How-to Guides

These are step by step guides on how to solve particular problems. The user can ask meaningful questions, and the documents provide answers. An examples of this type of document might be, “how do I compile an optimized model for ARM architecture?” or “how do I compile and optimize a TensorFlow model?” These documents should be open enough that a user could see how to apply it to a new use case. Practical usability is more important than completeness. The title should tell the user what problem the how-to is solving.

How are tutorials different from how-tos? A tutorial is oriented towards the new developer, and focuses on successfully introducing them to the software and community. A how-to in contrast focuses on accomplishing a specific task within the context of basic understanding. A tutorial helps to onboard, a how-to helps to accomplish a task.

Reference

Reference documentation describes how the software is configured and operated. APIs, key functions, commands, and interfaces are all candidates for reference documentation. These are the technical manuals that let users build their own interfaces and programs. They are information oriented, focused on lists and descriptions. You can assume that the audience has a grasp on how the software works and is looking for specific answers to specific questions. Ideally, the reference documentation should have the same structure as the code base and generated automatically as much as possible.

Explanations (Deep Dive)

Background material on a topic. These documents help to illuminate and understand the application environment. Why are things the way they are? What were the design decisions, what alternatives were considered, what are the RFCs describing the existing system. This includes academic papers and links to publications relevant to the software. Within these documents you can explore contradictory and conflicting position, and help the reader make sense of how and why the software was built the way it is. It’s not the place for how-to’s and technical descriptions, and instead focuses on higher level concepts.

Proposal

Following the model outlined above, the RFC proposed the following high-level structure for the TVM documentation with specific suggestions for individual documents.

  • Landing page
    • Introduction to TVM
    • Links to major sections
    • Full table of contents
  • Introductory Tutorial
    • Installing TVM, import a model, and compiling it to target platforms
  • How to
    • Installing TVM
    • Contributing to TVM
    • How-tos that are described as tutorials in the current documentation
  • References
    • Language reference
    • Current API reference
    • Specifications(e.g. log format)
  • Deep Dive
    • Design and Architecture
    • Literature
  • VTA
  • FAQs

Phases

The documentation refactoring will follow the following phases:

P0: Preliminary work

Preliminary work to reorganize the documentation structure. Some of this was completed in PR #6146.

P1: Categorization of existing documents

Creation of new documentation categories in existing code base, along with top-level landing page.

P2: Restructuring of existing documents

Existing document will be refactored into the new categorization framework.

P2+: New documents

New documents will be contributed by the community according to this structure, in line with the sections outlined above.

P3: End to end introductory tutorial

A full end to end tutorial will be written that describes how to install TVM and supporting software, importing a well-known trained model, and compiling it to different target architectures with optimizations.

6 Likes

Thanks @hogepodge for the proposal, with some prelimary effort along the lines of P0 and P1, we have already make the structure to roughly reflect the overal organization https://tvm.apache.org/docs/