Sitemap Revision
Link to sitemap: https://drive.google.com/file/d/1EbLU4-NiTWhVIpGVZt4k9es2FB2ZjG3X/view?usp=sharing
Initial Feedback:
Feedback on the site map
General notes
On entry points
I am thinking these are literally "entry points"—that is, places that we expect people to start looking for documentation when they aren't sure where to find it?
If so:
- The
arti
crate itself is probably another entry point. - I'm thinking that we should ensure that these all refer the reader to the same information overview.
On flexibility
I'm looking over this map under the assumption that it isn't too hard to revise it later on in Arti's lifecycle as we add or remove pages, or decide to split up a category. Is that right? If so, great. If, on the other hand, this map and these categories needs to be "set in stone", then we should probably spend even more time on them.
(ahf comment: if we know now there are pages we don't need, then it would be smarter to say it now so they don't spend time making them, but i do think we have a lot of flexibility here) (nickm: right; I was thinking about the case where we want to change something down the road.)
On external resources
Since we aren't planning to encompass all of the Tor Project's documentation into a single site right now, we've got to refer to external documents. With that in mind, it probably makes sense to think about places where we'll be referring to other documents in our universe of documents?
In particular, there are a couple of places where I think it makes sense to call out to other teams' documents, including "More about Tor", and "Tor Specifications".
Specific suggestions
I think we might need a "getting started" section somewhere that effectively asks the user what they want to do, and directs them to the actual resources they need.
I think that someplace we should have instructions on how to configure arti, and plan to have a more or less complete explanation of all our options.
The "reference" section doesn't make a lot of sense to me; most of it is just a list of development plans from the README. I think maybe that could be a single section under a new object called "arti: development status"?
IMO "Test coverage reports" could just get removed from our documentation entirely.
"Safer Build Options" might belong under a "how to compile arti" section, which might in turn go under "getting started"
Once we have an RPC API working, we'll probably want to split "integrating/embedding arti" into "non-rust" and "rust" sections; the story of how to do this will be very different.
"Using Arti as a Binary" might be thought of as a user manual for arti-the-program.
It doesn't necessarily make a sense to have "rustdoc crate documentation" under this hieararchy; we don't have control over how that is built or laid out, or which parts of it are
Some alternative categories
Here's my own attempt to make categories for this information. I'm not on insisting on any aspect of this information architecture; I'm mainly sharing it in hopes that it might inspire something.
{Diziet writes: I skimread this list and the organisational scheme looks reasonable to me. I think some of this list may be quite aspirational. On the whole I think I prefer Nick's information architecture, below, to the proposal in the google doc.}
-
Main arti documentation site
-
About Arti
- What is Arti?
- Getting Started
- What to read next
-
User guide
- Who is this guide for?
- Getting Arti
- Compiling from source (Integrate "safer build")
- Using Arti: The bare minimum
- Starting Arti (as a proxy)
- Configuring your applications to use Arti
- Configuring arti
- Troubleshooting
- Basic topics
- Censorship circumvention
- Hosting an Onion Service
- What Arti can't do yet
- Running a relay (not implemented), write later
- CLI Reference manual
- Configuration reference manual
- Description of files on disk
-
Integrating Arti
- Three options: RPC, in-Rust APIs, or custom wrappers.
- Which is right for you?
- Custom wrappers
- Compiling for Android
- Compiling for iOS
- Arti RPC (not implemented yet)
- ... there will be lots of stuff under this.
- Arti in Rust
- Understanding Arti's architecture (basics)
- Embedding Arti in a Rust program: tutorials
- Topics in Rust and where to learn more about them.
- Your first arti program: using TorClient to connect to a website!
- Your second arti program: working with configuration!
- Your third arti program: Writing an onion service!
- More worked examples
- Links
- Where to find more information (links to rustdoc.)
- Three options: RPC, in-Rust APIs, or custom wrappers.
-
Contributing to Arti
- Getting started
- setting up your development environment
- fetching arti's source code
- running the tests
- submitting a patch
- code of conduct
- How to get in touch
- Project policies
- support policies
- semver conformance
- MSRV
- coding standards
- MR workflow conventions
- ...?
- Getting started
-
Development documentation
- Project status
- planned milestones and their status (if this even belongs here?)
- Arti's architecture overview
- Tutorials and topic-guides
- how to add new configuration options
- how to add a new crate
- how to expose a new API
- working with experimental features
- ensuring backward compatibility
- how we log
- error handling
- testing and mocking
- ... ?
- Developer tooling overview
- Working with coverage
- fuzzing
- benchmarking
- testing
- chutney
- shadow
- Design notes
- Project status
-
-
External resources
- Rustdoc documentation for top-level general use Arti crates
- Specifically,
arti
,arti-client
, and `.
- Specifically,
- Rustdoc documentation for special-purpose high-level crates
- Tor specifications
- Resources on the Tor website
- Rustdoc documentation for top-level general use Arti crates