Thanks a bunch @tt_su, lots for me to look at here. I’ll review and get back to you.
The SketchUp API documentation is a concise dictionary of the API’s modules, classes and their methods. It is not a teaching tool and the snippets that are shown are mostly taken out of context and often not that helpful.
Contrast this with the SketchUp C API which have no snippets at all.
Trimble and it’s SketchUp division are not really in the programming education business. It is not their responsibility to teach basic programming concepts. The web has free and paid tutorials on this available. Or a person can take a night course at their local junior college.
The same holds for Ruby. The SketchUp API simply extends core Ruby and a coder needs to learn Ruby first. If they don’t, then the SketchUp API documentation looks to them like a foreign language.
This should be done somewhere after your step 2 and before step 4. I know that enthusiasts usually don’t formally attempt to learn Ruby during 1 or 2.
There are many free resources to learn Ruby and Trimble need not reinvent the wheel here:
Exactly, this has been my misunderstanding with my recent foray into the API and Ruby.
Agree, and @Matt I’m not knocking the gist of what you said above. I remember how the learning curve was very steep back in the day (what? 12 years ago now?) … and I had a background and formal college coursework in programming myself.
Yeah, I understand that. It’s also not their responsibility to teach people how to use SketchUp to model different types of projects, but Aaron produces several YouTube videos doing just that.
I just feel like for a beginner who discovers SketchUp’s API, they most likely have a specific idea they are really excited to figure out how to solve with code. But you’re basically telling that person to forget about their idea, go learn Ruby basics from some learning source that has absolutely zero context in 3D modeling, and come back later once they’ve made a bunch of boring practice programs solving imaginary problems. Only then are they “worthy” enough to play around with the SketchUp API.
I feel like it would be great if there were a path to learn Ruby within the context of SketchUp. That would be so much more engaging and interesting. It would drastically lower the barrier to entry. But idk, maybe there’s just not enough demand to justify someone creating something like that? Maybe most SketchUp developers are already programmers before diving into SketchUp…
I feel like that “Automatic SketchUp” book was a great attempt at teaching Ruby in the context of SketchUp, but I know you’ve pointed out many “incorrect” teachings in that book (plus at this point, it’s so old…)
That said Dan, I personally own several Ruby books, and have taken a course to learn the basics. My problem is I don’t practice frequently enough to gain proficiency, so there are gaps in my knowledge, and I suffer from I don’t know what I don’t know.
I suppose it would be helpful for me to think about specifically what I think could be improved, and provide that feedback…
When I first started out, the way I learned was by studying the code in existing extensions. That simultaneously covered both Ruby syntax and SketchUp Ruby API. But of course, there are two problems with that as a learning method: 1) there is no assurance that extension authors have followed good practices either in basic Ruby or in use of the SketchUp Ruby API, and 2) today so many extensions are encrypted to protect intellectual property that one can no longer usually learn from the masters.
Apples and Oranges.
SketchUp is their product and helping users learn it is part of their product evangelism.
This is not universal however. Some companies do this free and some (like Rhino for example) charge for learning resources.
“Worthy” is the wrong word. It’s “being educated” enough to produce a working and stable extension.
There is no magic wand we can wave and make instant programmers. Sorry.
But all the Core Ruby and Standard Library docs are external. Any contextual courseware would constantly be referring to external documentation and reproducing what is already out there. At least for the basics of programming such as file I/O, iteration, reflection, etc.
And I wish Mr. Scarpino would update his book and release a new edition.
Yes many users who are very busy doing architecture may not have the time to get proficient.
Several of us have talked about starting a cookbook type of repository linked into the Files section of the Ruby API documentation.
A few of the Trimblers were interested at first, but then I got the feeling that their managers above them did not want to spend any company time (ie, money) on this expansion of the documentation.
So then we do have several (Julia and Thomas) who publish their own example repos and gists on their own time. Although beneficial, this also contributes to the spread (rather than the consolidation) of learning resources.
These days, probably. Several years ago, I’m not so sure.
I see several reasons:
- The old Ruby API documentation had its own issues (mainly, it was time-consuming for the team to maintain), but its structure more closely resembled how the end-user experiences SketchUp. I think it made it easier for SketchUp users to dive into the API.
- As Steve already mentioned, there was no encryption, so we could look at the code of existing extensions and learn from there.
- There were far fewer extensions, and SketchUp lacked essential tools. So there was a need for users to create extensions for their own workflows. Nowadays with the profusion of extensions, and SketchUp getting the essential features it lacked, there is less drive for users to create extensions. These days, if you need to create an extension that doesn’t already exist, it’s probably quite an advanced one.
While it’s not SketchUp’s “responsibility” to teach people programming, it is something that would benefit SketchUp long term and something I think a lot of us would want to do. We can’t do everything, but it would be good if we could help people get started.
We are already discussing showing how to set up developer tools like TestUp and SketchUp Rubocop in future dev meetups. Feel free to go through the installation/getting started notes and file an issue if there is anything that could need clarification or rephrasing. A fresh pair of eyes is very valuable to detect these potential threshold that we ourselves no longer see.
Speaking of sketchUp Extension examples, both ThomThom and I have a large number of open source extensions over at GitHub. Personally I’ve found it easier to understand such practical examples than the more “artificial” examples SketchUp has published.
My impression is that a lot of productivity extensions are created by “power users”. People who are not trained developers, but had some experience or took the time to dig into it. I’m one of them, I’m educated as a model maker, designer, illustrator, but poked into web design and got exposed to JS/PHP etc. So when I started working with SU and got exposed to extensions I found that “I can kindof understand these things. Maybe I can write something myself.”
That’s where we hope having examples we maintain can serve as more assertive examples. (hat being said, SketchUp have in the past offered a number of examples that would not have passed EW moderation. In general I’d vouch for most on our GitHub account.
That might be because EW defaults to encryption now. (I’m not sure why that is the case TBH.)
Personally I wished more extension developers would make their source for their free extensions available on something like GitHub (BitBucket, or GitLab) with an open source license. (I got a long backlog of adding an license to my older ones, but at least most of them are on GitHub now.)
Seeing more collaboration using tools such as GitHub is something I’ve wished the extension community would grow into. There’s a low of sharing and helping on the forums, but I really think there are great opportunities with collaborating via GitHub. It could also be a nice way to get introduced to extension development, contribute a fix or improvement to an existing extension. You’d help out someone who’ve spend their time making and maintaining something, and you get a change to get feedback from someone experienced.
You think the old docs were easier to understand? I’d like to hear what we might have lost over the time if that’s the case.
That’s an interesting thought. And kinda makes sense - there certainly seems to be an evolutionary explosion in the early days. But, I’m still finding a lot of ideas for new workflow improving extensions, my problem is that I have less spare time to execute them.
I agree. And I’d love to see it easier for people to get going with writing extensions. You see the patterning schools these, with programming becoming part of the curriculum. Being able to do some basic coding can help in many areas.
[quote=“Matt, post:7, topic:174348”]But idk, maybe there’s just not enough demand to justify someone creating something like that?
There is something to this. Teaching is hard, very hard. There’s a lot more users of SketchUp than there are developers. Thus it’s easier to justify dedicated resources for training for SketchUp itself than for an API. And to teach an API you need someone who is tech savvy and experienced. Hard to get someone with that background willing to do only training instead of working on the product itself.
So, we (Extensibility) got to work with some tighter constraints, we end up doing it all. We do the development, the support and making all the tools and documentation. Stretches us thin. Probably the biggest reason we tend to defer the basics of programming to existing material. And why I tend to link to the “Ruby in 20 minutes” as I hope that’s less daunting - you might eye some accomplishments without spending too much time outside of the SketchUp realm.
That being said, there is a lot of room for improvement. I’ve been advocating for us to spend some time to rework our portals, developer portal and API front pages. Making some focused efforts into making it easier to onboard. In addition to improving the existing READMEs, examples and guides, I’d love to make a series of videos breaking down the various tools and setups. That off source takes time, but I think it’s worth investing in this, as it’s key part of the platform. Releasing API features isn’t enough by itself.
I’m really glad you brought up this topic Matt. Because it confirms a few of my suspicions about barriers and opportunities we have. If you’re up for it I’d be keen on doing a video chat with you to pick your brain more in-depth.
Honestly, it’s been so long I can’t remember the specifics.
But my recollection is that the structure of the old docs tended toward a 1:1 mapping with the SketchUp UI/UX. Now, the structure of the new docs has a 1:1 mapping with the implementation (this is just the nature of how YARD works, there is not much you can do about it).
With SketchUp, we’re lucky that the API implementation is not too far off from the UI/UX (I hear it’s much worse for AutoCAD or Revit). But still, I think there are things that can be hard to understand for beginners. Frankly, I am so used to the API now, that I can’t give an example from the top of my head, but I remember feeling this strongly when the new YARD docs appeared.
The old docs, (Google era) had a lot of things missing or mistakes in them. We’ve worked hard to fill in that.
Maybe you’re thinking of the categories they used to have? “Entities”, “Observers”, “Geometry”?
That’s something I poked into reintroducing to the YARD docs:
If you spot what you missed from the Wayback Machine copy of the old docs let us know. Oldest arched version I find is this from 2013: Class Index SketchUp Ruby API
Commits · SketchUp/sketchup-yard-template · GitHub
I know Switching to YARD was necessary and overall a great thing! Thanks for your hard work in that regard.
Google “Automatic SketchUp” by Matthew Scarpino. It’s out of print, but the PDF is available for free. Here’s one link to the book.
My favorite book for learning basic Ruby is “Learn to Program” by Chris Pine. It’s funny, well written, and easy to follow. A great confidence builder!
I also have bookmarks to the current SketchUp API and the original “Pragmatic” Ruby online book. Yes, it’s out of date, but it still has 95% of what you need, and it’s super easy to search. (I can never remember exactly how to call a method, so I’m always looking them up in these two references.)
Last but not least, look at lots of open source code. ThomThom especially has plenty of good stuff out there that shows you good style and will help you to set up a proper SketchUp project.
My first forays into SketchUp API was from when an existing extension didn’t quite work the way I wanted, so I tweaked it. I had no Ruby knowledge, but I knew some code from my web developing days (PHP). I deciphered what was going on in an existing extension with reference to the SketchUp API, then wrote a few lines of my own. I really recommend that as an approach to learning - you get results quite quickly which is satisfying.
As you say though, there are so many extensions out there, and many are well polished, so the impetus for doing it isn’t as great as it used to be.
Having said that, I still come across times where I think “I wish I could automate this task”, so I think there is still room for tinkering.
It should be made more explicit perhaps that the .rbz files are actually zip folders, and if unencrypted, can be opened and edited. Happily, most of the simple ones are unencrypted. Perhaps we should encourage all extension developers with free extensions to keep their code unencrypted?
I’ve been wanting to see a github/gitlab/bitbucket field for extensions, so open source can be markes as such. And improve the extension submittion form to make it clearer the effect of encrypting - perhaps even review the current default-on state.
I think it would be a great idea to link the extensions page to the “developer’s page” on github. It would be a nice thing that can encourage that step from being a user to an extension developer.
There are already links (on the bottom of the left hand nav list) from the Extension Help pages …
What “extensions page” are you referring to ?
I meant the extensions page that showcases an individual extension. Something more to connect the user of a tool with the development of it.
Oh okay. I think the old EW 1.0 had this. But EW 2.0 does not yet have it. I think it has been requested by devs. Not a GitHub specific URL (as there are other code repository sites,) but something that links to where the user can engage more closely with the dev of the extension.
For now, (if possible) the dev might insert a URL of their choosing into the Description.
I think that the “For more information” link is a general link from the developer’s profile and not extension specific.