The most promising idea we've come up with so far about helping readers with sample code is to provide not just sample code but a real sandbox, so rather than us advising readers to copy and paste and customize and try, we can offer one click-to-try button (which requires log in, but then leaves them with code matching their situation). The Doc Tools team, working with the Repose team, made some progress on that and then got pulled off to work on SS50. I'll work on getting resumption of the try-it-now project moved higher in their backlog (prioritizing the Doc Tools backlog is my project for today, as it happens), but that's something we'll see much later and then can work to incorporate it in whatever we've published by then. Later.

In the API doc, we do things two ways: show a replaceable element within its larger structure, so for example DELETE /instances/{instanceId}/users/{name}<http://docs.rackspace.com/cdb/api/v1.0/cdb-devguide/content/DELETE_deleteUser__version___accountId__instances__instanceId__users__name__user_management.html>

         shows where variables are to be replaced and where constants must remain; show a code sample where usable values are in their places and brackets are removed, so for example DELETE /v1.0/1234/instances/d4603f69-ec7e-4e9b-803f-600b9205576f/users/demouser shows what kind of shape a valid instanceId is likely to have, and shows that it's not surrounded by brackets when used. That's the difference between a code sample (shows what could work) and a description of the method (shows the general shape of things). In our API doc, each service's API Operations chapter begins with a table describing all the methods, which means showing the shape rather than sample values; you can see an example at http://docs.rackspace.com/cdb/api/v1.0/cdb-devguide/content/API_Operations-d1e2264.html (scroll down to the Method-URI-Description table). That description, pulled together into one place rather than scattered across all the API doc, is the same as what you can see in the new combined API Reference, which I think will be offered at developer.rackspace.com alongside these SDK Quickstarts. If the API Reference describes all the methods, marking placeholders to show where values have to be plugged in, then I think sample code in the SDK Quickstarts has to show how things look with values plugged in.

For this publication we won't have try-it-now ready so I think the traditional choices remain: under-remind readers to customize (and frustrate some because they're trusting your guidance and you didn't  tell them everything to do); over-remind readers to customize (and frustrate some because they're not babies and you don't have to clutter the doc by telling them everything to do). To decide which is the lesser mistake, choose one type of reader as the primary audience for this document; do what's most likely to help that reader. Whatever you do, it won't always work: some people who need the reminder won't notice it and will grumble when their copy+paste isn't magic; some people who don't need the reminder will grumble rather than silently skipping past what they don't need. All doc works that way, and the main solution is to provide a rich enough documentation set that every reader matches something out there, and can easily find it. These SDK Quickstarts will be a good contribution toward adding support for beginner-developers, which is something we lack today. That's who I imagine is the intended reader for this, so I assume I should err in favor of explaining the obvious, but that's just my imagination. I wasn't part of designing the SDK Quickstarts, but audience analysis is usually part of document design and it helps to settle questions like how much to overstate and how much to leave implied.

You can start out publishing with or without reminders to customize, watch for reaction, adjust later as you get to know more about this audience and their expectations.

From: Ash Wilson <notifications@github.com<mailto:notifications@github.com>>
Reply-To: "rackerlabs/developer.rackspace.com" <reply@reply.github.com<mailto:reply@reply.github.com>>
Date: Tuesday, June 3, 2014 at 11:29 PM
To: "rackerlabs/developer.rackspace.com" <developer.rackspace.com@noreply.github.com<mailto:developer.rackspace.com@noreply.github.com>>
Cc: Rose Coste <rose.coste@rackspace.com<mailto:rose.coste@rackspace.com>>
Subject: Re: [developer.rackspace.com] incorporate feedback on consistency of SDK Quickstart with API doc (#290)


In src/docs/cloud-dns/getting-started/samples/create_record.rst:

> @@ -5,7 +5,7 @@
>  .. code-block:: javascript
>
>    var recDetails = {
> -    name: 'app.domain.com',
> +    name: 'app.example.com',


I actually brain-dumped a bunch about the issue of showing placeholder values in the contributing guide<https://github.com/rackerlabs/developer.rackspace.com/blob/master/src/docs/CONTRIBUTING.rst#placeholders>, with some discussion about the particulars in #200<https://github.com/rackerlabs/developer.rackspace.com/pull/200>. By the guidelines I wrote there, this should be something like {domainName}, since we can't know what domain will actually work for the user.

More generally, though: as I see it, the solution to "people are copying and pasting without reading" isn't going to be "add more text." If they aren't watching what they're copying in the first place, they're likely to miss whatever notice we could come up with, too, and it'd just clutter the text for everyone else. Hell, I'm guilty of this myself plenty of times, on pages with big bold notices saying "replace these values with your own." Sometimes you're just trying to get something to work quickly without really being in "learning mode" and you slip up.

This is a universal problem for this kind of documentation and I have to say I have never seen a good solution for it. We could intercept the browser's copy event and do... something... that wouldn't be incredibly annoying? Use an active login cookie to show tailored values for the actual user, like your real API key? Flag placeholders that need special handling with a special CSS class and style them to stand out from the rest of the syntax highlighting?

—
Reply to this email directly or view it on GitHub<https://github.com/rackerlabs/developer.rackspace.com/pull/290/files#r13370782>.