Improve the documentation

[arctic-hen7]

Right now, the Perseus docs have two problems: they're too built around natural language, and too difficult to maintain.

For anyone who's taken a look, the docs are huge for a project of this size, and utterly unmanageable. With the v0.4.x release, I want to change that by switching to a more Rust-focused documentation system, whereby documentation is made inline as a first priority for docs.rs, and then tutorials and guides are set up on the website.

The big question is about feature awareness though, which is complex in a project as large as Perseus. Rust's documentation systems aren't enough for this I don't think, and I feel many projects in the Rust ecosystem fall down because they simply don't have enough auxiliary documentation. That's the key word though: auxiliary. The documentation outside the Rust code must be secondary, and minimalist. By having documentation as closely coupled to the code as possible, I think the docs should become much easier to maintain, and much easier to understand and interpret, because we can use an existing, and very powerful, organization system (docs.rs).

The website's docs will still exist, but they'll undergo major changes: I want there to be a tutorials section that's more user-friendly, an advanced section that explains some of the architectural features underlying Perseus, and a reference section for explaining features to people. Any content in any of those sections that is architecture or code dependent will be linked to the relevant code by a comment, making it much easier to understand which parts of the system are interdependent. As for what exactly should go into the reference section, that's an open question.

I would love any feedback on this problem from others, particularly in the area of organizing the reference section of the website's docs. I want to move away from the quasi-essays I've written on each feature, but I still want people to be able to easily navigate the docs to find out about the features they want to understand. I feel, and this may just be me as the kind of person who wants to build a new car if I can't find one that suits my exact wants, that we need a whole new docs system for this. Almost like a concept map that draws the user through a nonlinear navigational system. Again, feedback would be great!

(For clarification on the 0.4.x release itself, that will move forward without these docs changes being complete yet, as a beta version.)

[github-actions]

This repo is set up to triage issues with Tribble, but this issue couldn't be processed. If you deliberately didn't use Tribble to report this issue, you can safely ignore this warning. If you did, something's gone wrong here.

[erlend-sh]

This might help you break down the problems you’re trying to solve, by providing a sort of ‘docs taxonomy’: https://documentation.divio.com/

The implementation of such a system is of course a massive effort and can only be feasibly done with the help of dedicated technical doc writers. Its usefulness for a nascent project is as a knowledge architecture to slowly strive for, one small step at a time.

---

The storybook approach to docs seems related as well: https://medium.com/storybookjs/storybook-docspage-e185bc3622bf

I feel like a whole lot could be gained just by having a tighter integration of docs.rs in your own docs site.

Or alternatively rendering inline docs the way docs.rs does it, but rather incorporated into your own docs system, without using docs.rs as an intermediary. That way to you can sort of build all additional docs as an extension of your root API docs.

[arctic-hen7]

That's fantastic, thank you!

[saona-raimundo]

I asked about implementing different "types of documentation" in Rust-lang users, and the answer is to use compilation flags to get different documentation. Here is the discussion
I imagine this can be used with different goals: understanding implementation, How-to guides, etc...
This would locate the documentation right beside the code.
A crate that uses this approach is clap, with the unstable-doc feature.

Another approach that might be interesting is tango.
I feel this is much focussed on "literate programming", i.e. explaining why the implementation is the way it is, as opposed to a how-to guide.

[arctic-hen7]

@saona-raimundo I'm very open to that idea, I'll take a look at clap's code, thanks!

[xpe]

The documentation outside the Rust code must be secondary, and minimalist.

I don't follow. Why must? What kind of documentation are you referring to?

If you mean that higher-level documentation is downstream of the lower-level documentation because it depends, I agree. If this is your meaning, I don't think you need to say "it must be secondary". You might considering saying something like "The higher-level documentation is downstream of and dependent on lower levels of the stack."

This may sound pedantic, but it has the advantage that you are separating out descriptive from normative claims. I think that discussions and communities work better when we drive out confusion and misunderstandings about five things:

• What is? (descriptive) This may include efforts to reach consensus, often by use of shared terminology.
• What is conceptually good or desirable? (normative) However normative this might seem, arguments in this sphere often rely on descriptive claims as ways to persuade.
• What tends to work? (descriptive) This suggest an empirical approach of balancing priorities and interests.
• Where do we want go? (normative) This requires a definition of we: who makes the decisions and on whose behalf.
• How do we want to get there? (normative+descriptive)

The documentation outside the Rust code must be ... minimalist.

Must is a tricky word, just like should.

I don't think you are suggesting e.g. "documentation outside the Rust code must be minimalist" as a first principle. I think you arrived at this conclusion via reasoning.

In my experience, must and should are often best avoided because using obscures the reasoning underneath them. Instead, I would lay out your thinking. You did quite a bit of that above. But I have more questions; do any of the below fit?

• If the goal is to drive adoption, it is an open question of what mix of effort into documentation (tutorials? narrow examples? full example? code-level documentation?) best serves that goal.

• If the goal is to maximize your ability to achieve some particular mix of {coverage, correctness & accuracy, and timeliness}, then I probably agree that logic would suggest prioritizing low-level documentation. Not only does it streamline and enable all downstream work, but I think many find it to be of particular value in the software development process itself.

[xpe]

... the docs are huge for a project of this size ...

What do you mean about "of this size"? Do you mean in terms of adoption? maturity? code base size? scope?

I would claim most successful projects around web frameworks, one way or another, find ways to build / nurture a lot of documentation. This leaves the question: how to get there from here?

... the docs are ... utterly unmanageable.

I think what you mean is that they are unmanageable for your current team, with your current expectations about "quality" which tend to involve a mix of (1) correctness/accuracy; (2) coverage; (3) timeliness; (4) organization; (5) discoverability. I think stating this out loud is important. I think each point can be spelled out in more detail. For example, w.r.t. 'discoverability', cross-linking between documentation can make a big difference. Many Rust projects do a wonderful job of this: an example would be a random number library being very clear what algorithms they use and where they come from.

I certainly do appreciate the desire for better tooling, but I think there might be a lot of writing (and thinking out loud) to figure out what this means. I think this issue is a great start for this thinking.

[arctic-hen7]

@xpe I say "must" because, from a maintainability standpoint, it is infeasible to handle new releases with documentation that is separate from the code when it's as large as the docs are for Perseus right now (I've rewritten several thousand words of documentation quite a few times now). In terms of "of this size", I mean for the sheer number of intertwined features Perseus has. It's not a massive project in terms of code, but there are a lot of things it does, and, as such, documenting all these is quite challenging.

My point is that, within the Rust ecosystem, it's regular to manage examples and documentation in the code as primary sources of truth for developers, and I think Perseus could probably conform to this a little more. Admittedly, my thoughts on this have changed, and I'll write more on this in the coming days, but I think having the docs that are part of the code be more primary is certainly desirable, especially because individual features are best documented at the function/struct/trait level, and, if these docs can show up automatically in an IDE, that improves DX significantly. Overall tutorials and guides should certainly be separate, but more fine-grained features should be documented through rustdoc first, rather than on the website.