🎓 Let's Talk Documentation & Learning

Reflecting candidly on the recent hackathon #beyondthespeckleverse, you’ve told us loud and clear that our documentation needs improvement. We aim to improve our resources for everyone—users, developers, normies, and geeks alike. We want to create a reference site and a store of learning pathways for you.

We invite the Speckle @Community to share resources they find exemplary from all perspectives. Your input will help us shape a more useful and user-friendly documentation site.

Here are some points to consider:

  • User Experience: Which documentation sites have you found the most user-friendly? What features made those sites stand out for you?
  • Content Quality: What level of detail do you prefer in documentation? How do you balance between thoroughness and brevity?
  • Learning Pathways: Have you encountered any particularly effective learning pathways or tutorials? What formats (videos, written guides, interactive tutorials) are most engaging?
  • Learning Preferences: Do you prefer long-form content or bite-sized pieces? Do you like step-by-step notes or snippets? Text or video?
  • Developer Resources: Which sites provide the best developer documentation? What elements (code examples, API references, etc.) are most useful to you?
  • Inclusivity: How can we make our documentation more accessible to beginners and experts? What strategies can we employ to accommodate diverse learning styles?
  • Structure and Organisation: Should we separate user guides, tutorials, best practices, tips and tricks from more granular API references and developer deep dives, or do you prefer an all-encompassing Speckle data hub that integrates everything seamlessly?

Additionally, we want your feedback on specific things you find missing from our current spread of tutorials and docs. Your insights are invaluable in helping us improve.

We see community feedback as a crucial contribution to Speckle as an open-source project. Whether you’re a coder or have ideas for improving the user experience, your insights are invaluable.
Unlike others, we will not put learning behind a paywall. We believe in open access for all.

Looking forward to your suggestions and experiences!

7 Likes

Hey @jonathon,

Personally I am missing a documentation like: https://www.revitapidocs.com/
Of course it does not give much context of the methods and functions, but there is a very brief overview on the functions/classes/methods nd their members, which really helps me a lot if i want to get things done quickly. I do not have to go through the entire documentationtype looking for a specific detail.

I will elaborate a bit more in 1.5 weeks but this is something that came to mind immediatly

KR

D

4 Likes

I’m missing some documentation on the API side.
The GraphQL explorer makes it easy to understand what fields are available and so on, but there is some conventions that are missing, like how DisplayValues are structured, how to handle ApplicationId and constructing speckle_types, to name some examples.

A thing that could be cool is to have a place where you collect 3rd party articles, projects, guides, etc. that uses/talks about Speckle, so one could get inspired by what others do, like an “Speckle Awesome List”

4 Likes

Any other software documentation that you like?

Yeah, here is a few:

2 Likes

I would throw three-js journey in there, the platform for courses and community is really well done.

2 Likes

Firstly, I’d love to see the tutorials and other docs go into the same place, such that tutorials can docs can easily reference to each other and such that when you search the docs you also search the tutorials and you don’t have to remember whether you found something you learned in the past in a tutorial or in the docs.

Secondly, I’d love improved Grasshopper and Python docs. When it comes to computational design, I think there are two important scripting languages 1. Grasshopper for (attributed) geometry related stuff, and 2. Python for everything else. With these two scripting languages you can pretty much hack together / link up 90% of engineering workflow steps.

Grasshopper
At the moment it’s really complicated to wrap your head around the Speckle Object and Speckle Geometry concepts, and how to properly create them in Grasshopper, and there’s actually some little bugs in there I think: Making working with Speckle Objects in Grasshopper (more) intuitive. This is also strongly related to what @chrkong mentioned about displayValues, speckle_types, etc.

Python

P.S. when it comes to Astro, there’s starlight.astro.build for building docs sites specifically.

6 Likes

+1 for improved GraphQL docs. After jumping back into Speckle after a decent time away I’m trying to wrap my head around when to use projects/branches/streams/model.

This may or may not be helpful @chrkong but I use Postman to query Speckle’s Graphql endpoint, and I find their schema explorer more intuitive to use than the Speckle GraphQL explorer.

3 Likes