The Tellenze blog

A Quickstart Should Give You Something to Change

A working example gives a newcomer a result. One small, understandable change can give them a way into it. A fictional library catalogue shows the difference.

· The Tellenze team

A navy paper theatre shows mushrooms, with a teal side tab, a river scene card and an open book beside it.

The catalogue runs. Nia would like to find a book.

In this fictional example, she's trying a library-catalogue tool for the first time. She has copied the starter files, followed the setup commands and opened a page with three sample titles. The quickstart ends with congratulations and a link to the API reference.

Nia wants to search for mushrooms. She can see that the application works. She's less sure which part of it she is allowed to change.

That is an interesting place to end a guide. The author has reached the finish line; the reader is just beginning to have a question of her own.

A first-use guide can make room for that moment. After the working result, give the reader one small change that makes sense, and enough support to see what it does.

The example needs a handle

For Nia's sample, the three invented titles are The River Atlas, River Birds and A Field Guide to Mushrooms. The search looks for a word in the title. Its starting term is river, so the page shows the first two books.

These are deliberately ordinary choices. Nia can read all the data at once, and she doesn't need to know the library's classification system to understand the result.

The guide points to the search term and invites her to replace river with mushrooms. Before running it again, she can make a reasonable prediction: the field guide should appear, and the two river books should disappear.

Now the change has an explanation she can inspect. She supplied a different term; the search selected a different book from the same sample. She can put the original term back and repeat the result.

The important part isn't the size of the edit. It's the relationship between the edit and the thing the guide is meant to introduce.

Changing the page heading could be a perfectly good exercise in a lesson about rendering text. Here, the subject is searching a catalogue. A new heading would leave the interesting behavior untouched.

Daniele Procida's Diátaxis guidance on tutorials treats a tutorial as a learning experience, with meaningful activity and visible results along the way. It also asks the author to keep the path dependable. Giving a beginner something to change needn't mean sending them away to invent a project.

For this guide, the freedom is small and deliberate. Nia knows where the term goes, what data it searches and how to return to the starting point. She can concentrate on the relationship the author wants her to notice.

Leave time to look at what happened

There is a way to spoil this exercise: put the replacement term, the full edited file and the finished screenshot next to a button labelled Copy, then immediately move to the next feature.

That might be convenient. It might also let Nia finish without ever considering which book the search should return.

A pause before the result gives her something to think about. No exam required. The guide can simply ask which title she expects to see, then help her compare the page with that expectation.

The Raspberry Pi Foundation's account of PRIMM describes Sue Sentance's approach to programming lessons: Predict, Run, Investigate, Modify, Make. Learners begin with working code they can read and discuss before moving toward their own changes.

That work concerns school programming and classroom conversation. It doesn't establish how much an adult will learn from a particular product quickstart. The useful idea here is the sequence: look at something that works, consider its behavior, and make a change that you have some grounds to understand.

A written guide has no teacher beside the reader. It needs to leave the comparison visible.

For Nia, that means naming the expected title and showing where the search term is read. If she still sees the river books, the guide can help her check whether she saved the edited sample and reran the right step. “It should work now” is a difficult instruction to recover from.

MDN's introductory interactivity lesson offers a familiar example of visible cause and effect: click an image and it changes; provide a name and the heading changes. The learner can connect an action with something on the page. It's an instructional example, rather than a measured promise about learning.

The catalogue exercise can do the same with a behavior that matters to its subject. There is no need to introduce sorting, pagination and relevance ranking in the same breath.

Keep the promise small

“Quickstart” covers more than one reader need. Someone who already understands the tool may only want the commands that get it running.

GitHub's quickstart content guidance makes that distinction useful: quickstarts serve a discrete, focused task and can assume familiarity, while a more complex learning journey belongs in a tutorial.

So a setup page can be finished when setup is finished. It should say what it has helped the reader do, and offer a clear route to a learning example. A guide aimed at a newcomer has a different opportunity.

Even then, one successful modification doesn't show that Nia understands the search engine, can maintain the application or is ready to use it with the real library. It gives her a small piece of behavior she has encountered herself.

Keeping the sample honest matters. If the exercise searches a local list, say so. A remote catalogue may change between attempts. A cached response may hide an edit. If a result also depends on language settings or ranking rules, choosing a different word won't necessarily produce the simple comparison the author intended.

The answer isn't always to make the example more elaborate. It may be to choose a smaller demonstration, show which part is being held steady, and link to the richer behavior later.

There can also be necessary setup before any of this is possible. Credentials, specialist hardware or a difficult domain don't disappear because the writer wants an inviting opening. A supplied sample can provide an early rehearsal, provided the reader knows what has been supplied and what remains to be learned.

If you're revising a first-use guide, try stopping at its first working result. Find one change a newcomer could make for an understandable reason. Follow that change through to the result, with the original still easy to restore.

You may find the guide already offers exactly that. You may find that every apparent next step opens an unfamiliar subsystem.

In the catalogue, the gap is modest enough to close. Nia changes the term, expects a mushroom book and sees it appear.

The application was working before. Now she has somewhere to begin.

Further reading