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!
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
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ā
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
I also love the FastAPI docs that @chrkong mentioned, and my first impression of the Strawberry GraphQL docs is good, and the Streamlit documentation is also great I think.
I love Jupyter Book, because it allows you to create interactive, Executable Python Content , and launch a Live Environment such as a Binder Notebook or Google Colab:
Today I also discovered Quarto, which I think looks slick and seems to work well with Python as well as JavaScript, because it integrates with Jupyter and Observable JS.
P.S. when it comes to Astro, thereās starlight.astro.build for building docs sites specifically.
+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.
So something I am missing a bit is a full āexchangeā matrix. Currently the āsupported elementsā will show you how things are exported and imported if you transfer within the same application (from RVT to RVT, from C3D to C3D) but it does not really show me what i can expect in other software (accross applications)
I can make assumptions about interpretations on the receiving part of course, but i continuously need to verify if these are correct. would be usefull in the āsupported elementsā table to have columns added like 'Default received in application X as: mesh/solid3d/ā¦"
That is an excellent point - we have in mind that a way to pivot (or an additional view) is to focus on key workflows in the spirit of āHow do I do X?ā but references to support that would be good too. Thanks.
That said it increases the surface area of things that could spiral out-of-date
Additionally, it would be very very handy if this table is then referring to the connector version at the moment of updating. Currently I have no clue as to how up-to-date the table is.
Strawberry GraphQL docs is good, and the 
, and launch a Live Environment 
such as a Binder Notebook or Google Colab:
