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.
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!
For a technical writer, it can be difficult to find those use cases and examples that bring the documentation home to the reader. This is especially so in an agile environment, where requirement- and functional specifications tend to the minimalist. When you’re explaining an intangible and complex concept like “nested groups in Crowd”, it’s good to have some concrete examples that your reader can identify with.
This week, we released Crowd 1.4. Crowd is a web-based single sign-on (SSO) and identity management tool. That’s complex enough. Now add one of a new features in this release, the esoteric “nested group”.
“Nested group” — Is that a cluck of broody chooks?*
I’m quite proud of the new documentation on nested groups. It has some good use cases and diagrams.
* A “chook” is what we call a chicken in Australia 🙂
Where did the use cases come from?
Given that I’m working in an agile environment, where documentation is not abundant, and also that I don’t have face-to-face contact with our customers, it might have been difficult to find meaningful use cases. So where did they come from? Our customers “talk” to us via our Confluence wiki and our JIRA bug tracker, as well as other channels like user forums, support requests, etc. For a technical writer, the community wiki and bug tracker can be a good source of information about requirements and the stuff that happens to our customers out there in the wild.
For the nested groups documentation, I gleaned a lot of information from people’s comments on the feature request in JIRA. Thank you to those people who made such informed and informative comments! All I had to do was transform the information into more generic examples and add some illustrations.
Diagrams on a wiki?
What’s so magical about Gliffy and these diagrams? It’s that you can create and edit the diagram on the wiki page. When you view the diagram, it renders as a JPG on the web page. But if you have wiki permissions to edit the page, you can edit the diagram too. The Gliffy drawing interface is very intuitive to anyone who has used other drawing packages. This means that the drawings are “part” of the wiki — anyone can update them (permissions permitting) at any time, from any place.
Where do other technical writers get their examples?
I’d be really interested to hear where you glean your information from, especially if you’re in an agile environment or writing the documentation from scratch, with very little information falling down the traditional SDLC waterfall to land neatly in your pool of words.
We’re not business analysts, so we don’t have the time to do a full use case analysis or requirements investigation. But we often do need concrete and real examples. Has anyone else mined a bug tracker, walked a wiki or surfed a user forum to find this sort of information, and do you have any other handy tips?
An illustrated use case for this blog post? 😉
A termite nest on a tree in Manly Dam Park (near Manly, NSW, Australia):