Holochain RSM Documentation -- what do you want to see?

Technical Discussion
#1

Hey folks. I’m getting ready to publish the new dev docs website (https://developer.holochain.org) for Holochain RSM. My initial promise is not to have a comprehensive resource, but simply that everything you read there is ‘not wrong’ for RSM. That means that the tutorials and the guidebook will be removed, and the core concepts, glossary, and install guide will be updated.

Looking ahead… what would be useful for you?

I plan on taking a fresh look at the dev docs once the current one is up, and my big questions for you are:

What didn’t work for you?

What concepts were hard to understand? Did the stories, metaphors, and pictures I used in the Core Concepts work, or did they fall flat? Was the Guidebook well-structured, and did it give you the info you were looking for? Specific criticisms please!

What did you need that wasn’t there?

Throw stuff at me. What sorts of gaps were there in the references or Guidebook? Were you looking for documentation on specific components? Did you wish there was better literature on best practices and design principles?

Thanks all, and happy new year!

3 Likes
#2

I’d like to see as a first level good Rust generated documentation. We certainly need the higher level descriptions, diagrams, tutorials, etc. but if at least every function, macro, and structure has something with some context, references, and code snippets then I won’t ever be totally lost.

#3

awesome @abrahampalmer ; I’ll give that feedback – I don’t know what’s happening with that, but (a) I know your packages have to be eligible for upload to crates.io before you can publish their Rustdoc-generated stuff to docs.rs. So it sounds like you’re talking about not just availability, but good quality comprehensive documentation on every little bit? I’m advocating for documentation on every struct property and enum variant too. I agree that good reference material allows you to pull yourself up by your own bootstraps.

#4

Yes, it is fine if it is published separately and/or available locally in the development environment, but that is what I am looking for.

1 Like