New URL for SketchUp's API documentation

Dan Rathbun

@mark h. said:

Chiming in here on behalf of Scott and the SketchUp team.

Hello Mark, and Welcome!

@mark h. said:

... and we've also talked about the need to improve tracking action against comments and suggestions. ..., but we can do better at using your input to improve the quality of documentation.

Google, (your GE division, and your Dev team,) need to understand our bewilderment, frustration, and exhaustion.

Bewildered because, in our minds, Google is one of the largest software companies, on this planet. We wonder why, given the quality of Google's documentation, for it's other APIs, that the Sketchup Ruby API, has been allowed to flounder for so long, in such a state of disrepair.

Frustration because, the customer base for Sketchup, are engineers. Engineers who create documentation, every day, and use Sketchup as a part of that workflow. Engineers who are taught early, the importance of configuration management (revision control, ECOs, DCNS, etc.) and would never think to have out projects built by issuing obsolete plans to the field. (a shop, factory, build site, etc.)
And, so these same engineering types, have had to rely upon, an obsolete and erroneous API dictionary, to build plugin projects. I am not sure what the descriptive word would be for how we "feel" each time we need to do a lookup in the API. Quite likely, it varies, from one rubyist to another. "distaste?" "aversion?"
Given our field of work, you'd have to admit, that our frustration is natural.

Exhaustion because our brains are so tired of trying to remember what in the API documentation, we have to reject, and what is valid. And so very weary of fighting the near "losing battle", of steering the ruby newbies away from the pitfalls of the API errors, (with it's often confusing or incorrect code samples,) and add to that, distributed example scripts and standard extensions (DCs, Sandbox, etc.) that promote poor programming practice, disrespect for the global ObjectSpace, or other violations of good Ruby coding standards.

Whew! (I feel better now.)

Don't you (or anyone there on the team,) take any of this personally. We do like you (all of you, and individually,) on a personal basis!

This issue is on a separate level. This is WE, the users, the plugin developers and the customers, of the product (Sketchup,) talking to the VENDOR, Google, the provider of the product and it's associated services, as a non-personal entity.

thomthom

Hi Mark.

Thanks for chiming in.

@mark h. said:

Looking closer at the downside of losing community comments, we do have all the comments from the old site. We'll be cooking up an interim solution for tracking feedback on documentation, and we've also talked about the need to improve tracking action against comments and suggestions. The old site wasn't a wiki-style model (and the new one won't be), but we can do better at using your input to improve the quality of documentation. Stay tuned for updates on this -- likely on a new SketchUcation thread.

I'd really really like some mechanism where we could contribute with feedback to the areas of the docs which is confusing, lacking or just plain wrong. We had hopes for the old commenting system (though inline comments would have been better, and with formatting) but the comments there didn't seem to ever migrate into the docs. (Which is why we eventually began to rely on them.) Another problem with the commenting section was that they where only visible when viewed with English locale preferred. If you had a different language preference, you'd still get the English docs, but you'd be transferred to a new URL that didn't display the comment.

I really hope a rewamp can be done of the docs. Things like the excessive use of .typename is one of the things I've been lobbying to have removed. It's the most common performance killer in plugins - and I see it all too often. And I belive it is because the API docs use that method all too often in it's examples. More info on the matter.

I submitted my thought to the feedback form you linked to. Thanks.

david.

An emphatic ditto to everything Dan wrote!

Mark H.

Hi again Dan, Thom (and everyone else!),

We definitely don't take this kind of feedback personally, but it may be also to clarify that code documentation falls on the same SketchUp engineers who are also writing new code or fixing bugs. In that context, we do have a challenge to prioritize improving documentation against improving SketchUp. I hope you all aren't personally offended by that reality.

But this is besides the point of how we can improve. I'll take a crack at summarizing the main points of feedback that Dan and Thomas have offered so far. Please chime in if you think I've misinterpreted this input. (PS The points below are aside from the specific documentation corrections/edits that have already been made via the comments on the old site).

-- In-line commenting/edit suggestions. My question here: is this a request to suggest documentation edits or to ask for clarification?
-- Localization. This is clearly important and something that I know the larger Developer Relations team is aware of.
-- Powerful look-up tools for searching API documentation. It also sounds like it would be handy to be able to set personal bookmarks to reference points in documentation.

Mark

thomthom

@mark h. said:

-- In-line commenting/edit suggestions. My question here: is this a request to suggest documentation edits or to ask for clarification?

It would be nice to have a dedicated channel to provide comments on the API docs - where it's lacking, misleading or wrong. Something that goes to the maintainers of the docs and hopefully get some time to update.
In addition it's useful to be able to make comments on the API pages themselves in order to make public notes for other readers - until the docs are corrected.

If it was possible to add notes next to each method and class (like in Google Docs) that would be nice.

@mark h. said:

-- Localization. This is clearly important and something that I know the larger Developer Relations team is aware of.
I didn't have a wish for localization of the docs. My concern was that the old site tended to forward you to an localized version without any of the user comments - the site would still be all English though. And there was no way to select your preferences - other than changing browser preferences which then affected all site. A design which many of Google's pages/sites got. I may have Norwegian locale, but I want to access the English version of sites - they usually got more content and update more often.

Dan Rathbun

Mark:

Look at the Sketchup User's Guide Page

See all those expandable / collapsible topics ??

That's what we need on the API pages !!

1) It's wastes so much time scrolling up and down.

Just as in our code editors, where blocks (class, module and methods,) can be folded (collapsed) and unfolded (expanded,) we need each section (Intro, Constants, Class / Module Methods, etc..,) expandable/collapsible.
Each method section, also expandable/collapsible.

2) For gurus.. we don't need to see the code samples (by default.) So they should be in a collapsed subsection.

when the Samples subsection is expanded, only the generic (1st) sample is shown (it's not within a exapnding box itself.)* We also wish to donate code samples.* So each additional sample box (below the primary one.) would need a Description and itself be collapsible.

3) The same goes for additional subsections, of each module section, ie:

The BUG / Revision History (Google SUDT generated.)* Community Comments (separated into subsections, via input form dropdown control,):
API Bug Reports (for this specific method.)* API Documentation Report (for this specific method.)
Error / Typo in Method Definition* Error / Typo in Code Sample* Clarification Needed / Missing Information* Tips & Tricks & Gotchas (for this specific method.)

We need formatting similar to Google Docs, text color, bold, italic, code blocks, urls, etc.* Questions

These are usually posted by newbies, or those that do not understand, this is the wrong place to post "How do I do ..." questions. So these would be posted into the GG Ruby Developers forum instead. But would insert info from the input form, that others can use to help them. Such as their OS, their Sketchup version & build number.

Now.. obviously to many nestings, will push things to far right.
SO ...
I'd like to see something similar to how Wikipedia pages work. Where there's the "Doc" Page in front, and a "Talk" page, behind the Doc page.
Alot of the Community donated content, goes on the 2nd "Talk" page (or maybe there are more than one overlay pages,) .. anyway, these other pages, are ALSO organized into the same sections, as the Doc page. If we are "within" a certain method subsection, and we click "Tips & Tricks", or whatever... the relevant overlay comes to the top.. with the same sections & subsections expanded.

ADD: Collapsing and expanding sections should work like it does in a code editor, or generic navigation tree controls:
NotePad++ uses:
ALT+0 collapse ALL levels
ALT+1 collapse 1 level
ALT+2 collapse 2 levels
.. etc.
SHFT+ALT+0 expand ALL levels
SHFT+ALT+1 expand 1 level
SHFT+ALT+2 expand 2 levels
.. etc. up thru 8
CTRL+ALT+F fold current level
SHFT+CTRL+ALT+F expand current level

The user's mouse would need to be in the "page control" I believe. Trapping ALT may be a challenge, and browser make use of CTRL for their hotkeys.
Perhaps just the numbers for collapse, SHFT+num to expand?

Oh wait... just tested in Windows File Explorer, it use the numeric keypad keys *, +, -, arrow keys,etc.

Dan Rathbun

Here's a Google Chrome Bookmarks export (html file,) for the SUAPI with all links and icons updated to the new Developers URL.

SUAPI_Links.zip
Looks like:

In Google Chrome.. use the Bookmarks Manager > Organize > "Import bookmarks from HTMl file..."

It is a standard Netscape bookmarks file, so it will also likely import into other browsers, as well.

Dan Rathbun

I just realized.. we have a myriad of URL links here on SCF (mostly in the Developers Forum,) that point to the old google code docs.

What happens when they stop redirecting from the old urls?

thomthom

If they stop redirecting. Hopefully they follow good practice and don't remove it.

Pout

For me it's simple:

For registered users give the opportunity to comment on incorrect information/give more explanation and give possibility to add code examples. I always like the way PHP does it: http://php.net/manual/en/function.include.php

If you give us the tools, we help you with the content...