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:
