Documentation Revamp

[GregoryComer]

We are looking at revamping the ExecuTorch documentation to improve clarity and streamline the getting started experience. I'm creating this discussion post to lay out some of the goals and ideas. We are interested in any thoughts, feedback, or ideas related to documentation structure, content, and form.

Goals

The current round of documentation updates are motivated by the following goals:

• Users should be able to quickly understand what they need to do to run on a model on ExecuTorch, without needing to read through reference material or be exposed to unnecessary complexity.
  • A new user should be able to install the framework + libraries, export their model, and write runtime code entirely from reading the getting started guide
• Documentation should flow logically, especially for the initial getting started experience. Concepts and actions should be presented in a logical order, consistent with the user journey.
• Documentation should give the appearance of a mature framework.

Principles

To accomplish the above, I propose the following approach and principles:

• Clearly separate getting started and reference material. The getting started flow should cover the most common uses cases and naturally guide users to more advanced documentation, as appropriate.
• Use in-line code snippets as main way to inform users on how to use the platform, where possible. In-repo example code, runners, and demo apps should be supplemental and not required to understand how to load and run a model.
• Provide dedicated flows for Android + Java, iOS + Objective-C/Swift, high-level C++, and embedded C++. Avoid making users read through low-level documentation for common mobile use cases.
• Split tutorials out from reference documentation. A lot of our backend information is in tutorials, for example, often not really in a "tutorial" format.

Proposed Top-Level Structure

I'd like to re-arrange a few things, especially around the top of the docs and getting started section. Here's what I propose:

• Introduction
• Usage
  • Getting Started
  • Exporting a Model for ExecuTorch
  • Using ExecuTorch on Android
  • Using ExecuTorch on iOS
  • Using ExecuTorch with C++
  • Troubleshooting, Profiling, and Optimization
• Backend Delegates
  • XNNPACK
  • CoreML
  • ...
• Developer Tools
• Runtime
• API Reference

This moves the most used documentation to the top. The remaining sections (IR Specification, Compiler Entry Points, Quantization, and Kernel Library) are in an okay state, as far as reference documentation. I'm also leaving LLMs out, for now, as they are complicated enough to deserve their own pass. Let's take a look at the LLM/GenAI-specific docs once we figure out the core framework docs.

On the above, key changes compared to the following are:

• Don't tell users to build from source for python and mobile getting started, focus entirely on package managers. Source build info should be in the dedicated Android + iOS pages. C++ will always want to build from source.
• Pull a lot of the Android and iOS documentation that already exists up to the top level, giving it logical parity with the C++ flow.
• Standardize the documentation for each delegate, ensuring that the following is clearly explained:
  • Basic usage, including a python snippet for export demonstrating the appropriate partitioner and imports.
  • Build / linkage information. What CMake targets are needed?
  • Hardware targets - what hardware does the delegate support or require?
  • What quantization options does the delegate support?
  • What partitioner options are available?
    • For example, per-op mode (XNN) or AOT compile (CoreML).

[GregoryComer]

I've started on drafting a new getting started experience. There's still a bit of work left to do, but the draft is available at #8179.

[GregoryComer]

CC @mergennachin@byjlw@cbilgin

[byjlw]

For clarification. This is the directory structure/map for docs/src?

[GregoryComer]

Yeah, more or less. It's intended to be the structure for the navigation in the docs. The directory structure under docs doesn't exactly match the nav menu - we could potentially clean that up. See index.rst for the actual definition.

[GregoryComer]

Thanks everyone for the initial feedback on the PR. I met with @byjlw today to discuss our approach to documentation and next steps. There 's a lot of good ideas floating around, and I'd like to align on a couple of key questions with everyone who has strong opinions.

Regarding the initial Getting Started / Quickstart:

• I've traditionally been of the opinion that the goal for Getting Started is to get the user to running their model in their app as quickly as possible. Focus on a minimal set of install steps and lines of code to have the user running the model from their code in under 10 minutes.
• Assume that they have a PyTorch model, a codebase, and can construct an input tensor.
• Talking with Jesse, his approach is more than the Getting Started should be for the user to build confidence that it works. We should give them a PTE to download so that they can skip the export step. We should also consider building more abstraction layers (for image/audio/etc.) to hide "raw" tensors, as they might scare users. We should also give them an interesting model to run (he suggested speech recognition, or maybe image recognition). We should point them towards runners and such rather than having them write any code. Jesse, feel free to correct me if I've incorrectly summarized.
• I definitely understand where he's coming from, though I'd like to discuss this more. At a minimum, I'd like to iteratively improve the docs without needing to wait for us to build out major components. Maybe we can compromise for now on re-working my new getting started draft to use a simple vision model like MobileNet?
• The other factor is that I'm trying to keep the user from needing to pull down the repo and build from source for common mobile use cases. If we rely heavily on runners and in-repo examples, it necessitates much more setup for the getting started experience, which increases friction.

Regarding the target user personas:

• Are we more interested in targeting users who are familiar with PyTorch, aren't scared of working with tensors, have a model in mind to run, and have a general idea of how their model works? Or are we more interested in trying to provide a "gentle" / "curated" experience for people who are intimidated by the above and have minimal domain knowledge?
• I like the idea of reducing technical complexity for onboarding in theory, but it's relatively at odds with how we've been building the entire framework up to this point. Doing it likely requires a lot more abstractions (around image handing, classifier heads, etc.) and likely being much more opinionated about model structure. That or we provide a lot more "curated" example runners for specific use cases (maybe this is the way to go?). Though I'd argue that running models out-of-box without understanding them is a fundamentally different use case than what we've been targeting.

Thoughts? CC @byjlw@mergennachin@cbilgin

[mergennachin]

Yeah, I'm in favor of iterative approach. In particular, I'm taking a pragmatic approach, breaking things down into incremental steps that can be done in parallel or sequentially.

Some things will take a lot of time. For example, pip install executorch that installs everything needed for host could take some time. In those cases, I'd like to still make progress on the documentations overall by providing alternative path (build from source), and make a separate issue for pip-install-readiness (and @larryliu0820 and others can tackle in parallel)

Some things will take a minor efforts, and in those, we should just do them directly.

[mergennachin]

If we rely heavily on runners and in-repo examples, it necessitates much more setup for the getting started experience, which increases friction.

I actually don't wanna rely on in-repo examples and runners much for our documentaitons.

[mergennachin]

Are we more interested in targeting users who are familiar with PyTorch, aren't scared of working with tensors, have a model in mind to run, and have a general idea of how their model works?

This ^^

The first target persona will be mobile engineers, who want to build AI powered mobile apps.

But they can do a small prototype using torch and have basic understanding of ML. In particular, has some basic knowledge of machine learning concepts, but limited hands-on experience. She has worked on projects involving simple NLP tasks, such as text classification and sentiment analysis.

In general, I don't want to be curated since these curated experiences will not translate to other generic use-cases.

[GregoryComer]

Also, at Mergen's suggestion, I've created a doc-revamp branch on the repo. I'll move my PR to target that branch and hopefully we can iterate quickly to get things landable in main. I do like the idea of a branch in the short-term, as I've left a lot of placeholders to docs that don't currently exist.

Edit: The new branch is now executorch-just-works.

[GregoryComer]

I've prototyped a new top-level structure and put a bunch of placeholders in #8287. We are iterating on the executorch-just-works branch, which is expected to merge into master in two weeks.

[GregoryComer]

We're about ready to merge the initial round of doc updates back into master from executorch-just-works. I've also drafted a site map: https://docs.google.com/document/d/1qxo3Tkaz5QPxPyH1ckDoVwOEfjzPU5BwHKSLEt6PIcg/edit?tab=t.0#heading=h.1q2j4q4smd2b.

CC @byjlw