Blog Archives

Diagrams to introduce an SDK

In an effort to understand an SDK, I found myself drawing diagrams. Just to get the concepts into my head, and to visualise the way the bits and pieces fit together. It turned out that those diagrams are useful to more people than just me. My diagrams became part of the SDK overview that I was writing.

SDKs are conceptual and tricky to grasp at the best of times. This one offered a couple of special complexities. I’d heard from many sources that people were having trouble getting started with the SDK.

My goals for the introduction to the SDK

What are the two complexities that I wanted to illustrate?

Firstly, there are a few different paths that you can follow to achieve your goal of using the SDK to build a machine learning pipeline. For this doc, my audience is fairly comfortable with machine learning, so that’s not the complexity in this case. But it is confusing that there are a few different ways of putting a pipeline together.

Secondly, your code at some stage ends up in a Docker container managed by Kubernetes. It’s not a given that my audience is well up on Kubernetes. And they almost certainly don’t know how the containerisation of their code relates to their use of the SDK.

The doc and diagrams

The doc is an introduction to the Kubeflow Pipelines SDK. It starts off with an overview of the packages in the SDK, then describes the four ways you can use the SDK to build a pipeline, depending on your starting point and your use case.

The first use case describes the most common usage of the SDK: creating pipeline components from existing code. The section starts with a diagram:

As you can see, the diagram has some minimal code snippets. Just enough to give readers a hook to attach more information to.

Note: The diagram in this post is a png file, but in the docs I’ve used SVG (XML). The use of the XML format means that we can internationalise the text, when the time comes to provide the Kubeflow docs in languages other than English.

After the diagram comes a more indepth description of the diagram, with more meat to the code. It’s still probably not enough for people to copy, paste, and start coding, but that’s not the goal of this doc. The goal is for people to gain a conceptual understanding of what fits where, and of when you’d use this particular workflow.

At the end of the section is an info box containing links to further information and examples.

The subsequent sections follow the same pattern:

  • Diagram with minimal code.
  • More indepth explanation with more code.
  • Pointers to detailed docs and examples.

Progressive disclosure

The design of the doc mimics the user interface design principle of progressive disclosure.

The doc starts by revealing the primary concepts and code patterns in each use case. That allows the reader to grasp the similarities and differences between the use cases.

Next, for readers who want to know more about a particular use case, the doc gives a little more information below the diagram. There’s just enough terminology and code to give people a good idea of what the workflow involves.

For novices, that level of information provides a logical compartment into which they can wedge their growing understanding. They can go away and look at more detailed docs, then come back and fit that new information into the right place in the use case.

For readers who are already experts in most of the required areas and just want to know how this particular SDK works, the information under the diagram may even provide enough context to start coding.

Lastly, for each use case the doc provides links to detailed information and examples.

Do people like the doc?

I wrote the doc because I’d heard people were having trouble understanding how to use the SDK. My initial reason for drawing the diagrams was for my own understanding. But then I realised that the diagrams would probably be useful to others too. I showed the diagrams to an engineer, and he agreed. I showed a draft of the doc to an intern who had just started learning how to use the SDK. He said the diagrams would have been extremely useful if he’d had them two weeks earlier when he was starting out with the SDK.

The doc is new, so it’s too early to tell how well it performs for a wider audience. I plan to check the analytics and ratings in a few weeks’ time.

Do the diagrams hit the right spot between too naive and too complex?

I’m sure there are improvements we can make in the way I’ve described the technology. We’ll iterative and improve over the next weeks and months, as we do with most of our docs.

Still, I think we should be careful to keep a certain level of naivety. After all, these diagrams helped me kickstart my understanding of the concepts involved in using the SDK. Other people reading the docs will be at the same level of not knowing stuff when they start out. We need to keep that level in mind. The curse of knowledge is a powerful thing!

STC Summit day 2 – Progressive disclosure

I’m at STC 2012, the annual conference of the Society for Technical Communication. This post contains my notes from a session called “Improving the user experience by applying progressive information disclosure”. The presenter was Andrea L. Ames.

Andrea started by saying that our job as technical communicators is to make our users as successful as possible with our products. That means writing the content, and putting the content in the right place.

Andrea’s presentation covered:

  • What is progressive disclosure (PD) in a traditional world, with a traditional task-oriented help system. Andrea mentioned that we may have been doing PD for years.
  • The new twist – applying PD to the information experience, in particular the UI
  • Why it seems easy, but is not that easy to do.
  • Some quick steps towards PD.

What is progressive disclosure (PD)?

PD comes from the user experience world. It means that we take something that is essentially complex, and simplify it by giving the user only what they need right now, then reveal the rest later. We visually hide complexity. After all, sometimes the user will never need to see the complexity, depending on the path they choose.

PD is a technique used in interaction design. Wizards, for example, are a PD mechanism. PD has been around since the early 1980s.

PD can be applied to information as well. Not just the interaction or UI. We can help the user get just what they need, without being overwhelmed. Remember that their goal is not to read the documentation.

What is high value content?

Telling people how to manipulate the user interface is the lowest value content that you can write. High value content is telling the customer how they can solve their business problem.

Andrea described a user’s goals like this:

  • Goal 1 is to solve a problem.
  • Goal 2 is to use a specific tool to solve the problem.
  • Goal 3 is to read the help or documentation.
  • Even worse, if people have to read documentation on how to use the help, that’s goal 4.

What is progressive information disclosure?

Progressive information disclosure is the ability to provide the right information in the right place at the right time. It:

  • Assumes most users are at the stage of competent performer to proficient performer, rather than novices or experts.(From Sarah: This is a key point. Very useful.)
  • Postpones the display of novice information, background, concepts, and extended reference information, until the user needs and asks for them. This means that we need to thoroughly understand the context and what it means to the user.
  • Reduces complexity by revealing only what the user needs to know for the current task.


  • Reveal the information in an ordered manner. Each layer builds on the previous one. For example, a user starts by skimming the field labels and inline text before resorting to hovers and clicks to find help.
  • It should be a guided journey, not a scavenger hunt.
  • Design around the ideal information experience, assuming you have no resource or time constraints. This is your model.
  • Then you implement what you can, taking your constraints and dependencies into account.

It’s not entirely new

Andrea showed us an example of traditional contextual help, and discussed how elements of that design are already practising progressive information disclosure.

But there are problems with traditional information development methods

Traditional help information is task oriented, but it is usually task oriented in that it tells people how to use the UI. It also tells people the obvious things, such as how to type your username in the username field.

Much of the text in the UI is written by the developers.

The next evolution in progressive disclosure

Technical communicators need to get closer to the task than the help gets us at the moment. We are closer with embedded help, but it’s still out of the main taskflow. We need to write the right information in the UI. We need to influence the design of the task and all the related UI areas. The idea should be that we write as little as possible, because it’s not necessary.

How? Anything you can drive into visual design, interaction design, or algorithm, means that there’s less to write. For example, write the field labels on the UI.

The prerequisite is that we think more, and write less. The problem comes if we have very complex software, and if we don’t have the skills to simplify it ourselves. In that situation, what can we do?

  • Break out of complacency and be vigilant. Keep trying. Own the information experience.
  • Make sure we’re involved throughout the design experience. Become more influential in our organisations.
  • Don’t let the developers think for us. Sit in on the development design meetings, and contribute. Discuss with our team how to approach this. Push back on the words often spoken when the UI is complex: “We’ll fix it in the help.” No! Fix the UI. This is where the customers most need us.
  • Keep an eye on the volume of content produced, and reduce it where possible. Don’t assume we need a help topic per screen.
  • Be in the moment, and think about the right thing to do in this moment.

More ways to write less and think more:

  • Document the UI in the UI.
  • Think about how we can raise issues.
  • Ask questions about what we don’t know. Our questions are probably the same as the users’ questions.
  • When testing information, take user input into consideration. But make sure we understand the root cause of their feedback, rather than just doing exactly what they say.
  • Design the right solution, based on the root cause, because we understand the problem.

A practical guide

  • Start with the product, making it as obvious and self-evident as possible.
  • Consider the users’ stages of use.
  • Decide on the types of content we need, such as help with controls, panels, domain.
  • Improve the help, and make sure we are supporting the use of the UI with the non-UI based assistance (documentation).

A cool quote from Andrea

Andrea wants to write 10% of what she writes today, and have customers universally love it. And she wants people to buy products because of the help.


Andrea is great to listen to and watch. She is amusing, enthusiastic and knowledgeable. Thanks Andrea for a great session.

%d bloggers like this: