You are here

thinktime

Cancelled

Seth Godin - Thu 09th Nov 2017 21:11
All those meetings you have tomorrow--they were just cancelled. The boss wants you to do something productive instead. What would you do with the time? What would you initiate? If it's better than those meetings were going to be, why...        Seth Godin
Categories: thinktime

Winning a yoga race

Seth Godin - Wed 08th Nov 2017 19:11
It makes no sense, of course. The question this prompts is: Are there places you feel like you're falling behind where there's actually no race?        Seth Godin
Categories: thinktime

Pia Waugh: FWD50 Keynote: The Tipping Point

Planet Linux Australia - Wed 08th Nov 2017 13:11

I was invited to an incredible and inaugural conference in Canada called FWD50 which was looking at the next 50 days, months and years for society. It had a digital government flavour to it but had participants and content from various international, national and sub-national governments, civil society, academia, industry and advocacy groups. The diversity of voices in the room was good and the organisers committed to greater diversity next year. I gave my keynote as an independent expert and my goal was to get people thinking bigger than websites and mobile apps, to dream about the sort of future we want as a society (as a species!) and work towards that. As part of my talk I also explored what the big paradigm shifts have happened (note the past tense) and potential roles for government (particularly the public sector) in a hyper connected, distributed network of powerful individuals. My slides are available here (simple though they are). It wasn’t recorded but I did an audio recording and transcribed. I was unwell and had lost my voice so this is probably better anyway

The tipping point and where do we go from here

I’ve been thinking a lot over many years about change and the difference between iteration and transformation, about systems, about what is going on in the big picture, because what I’m seeing around the world is a lot of people iterating away from pain but not actually iterating towards a future. Looking for ways to solve the current problem but not rethinking or reframing in the current context. I want to talk to you about the tipping point.

We invented all of this. This is worth taking a moment to think. We invented every system, every government, every means of production, we organised ourselves into structures and companies, all the things we know, we invented. By understanding we invented we can embrace the notice we aren’t stuck with it. A lot of people start from the normative perspective that it is how it is and how do we improve it slightly but we don’t have to be constrained to assumption because *we* invented it. We can take a formative approach.

The reason this is important is because the world has fundamentally changed. The world has started from a lot of assumptions. This (slide) is a map of the world as it was known at the time, and it was known for a long time to be flat. And at some point it became known that the world was not flat and people had to change their perspective. If we don’t challenge those assumptions that underpin our systems, we run the significant risk of recreating the past with shiny new things. If we take whatever the shiny thing is today, like blockchain or social media 10 years ago, and take that shiny thing to do what we have always done, then how are we progressing? We are just “lifting and shifting” as they like to say, which as a technologist is almost the worst thing I can hear.

Actually understanding the assumptions that underpin what we do, understanding the goal that we have and what we are trying to achieve, and actually having to make sure that we intentionally choose to move forward with the assumptions that we want to take into the future is important because a lot of the biases and assumptions that underpin the systems that we have today were forged centuries or even millennia ago. A long time before the significant paradigm shifts we have seen.

So I’m going to talk a little bit about how things have changed. It’s not that the tipping point is happening. The tipping point has already happened. We have seen paradigm shifts with legacy systems of power and control. Individuals are more individually powerful than ever in the history of our species. If you think way back in hunter and gatherer times, everyone was individually pretty powerful then, but it didn’t scale. When we moved to cities we actually started to highly specialise and become interdependent and individually less powerful because we made these systems of control that were necessary to manage the surplus of resource, necessary to manage information. But what’s happened now through the independence movements creating a culture of everyone being individually powerful through individual worthy of rights, and then more recently with the internet becoming a distributor, enabler and catalyst of that, we are now seeing power massively distributed.

Think about it. Any individual around the world that can get online, admittedly that’s only two thirds of us but it’s growing every day, and everyone has the power to publish, to create, to share, to collaborate, to collude, to monitor. It’s not just the state monitoring the people but the people monitoring the state and people monitoring other people. There is the power to enforce your own perspective. And it doesn’t actually matter whether you think it’s a good or bad thing, it is the reality. It’s the shift. And if we don’t learn to embrace, understand and participate in it,particularly in government, then we actually make ourselves less relevant. Because one of the main things about this distribution of power, that the internet has taught us fundamentally as part of our culture that we have all started to adopt, is that you can route around damage. The internet was set up to be able to route around damage where damage was physical or technical. We started to internalise that socially and if you, in government, are seen to be damage, then people route around you. This is why we have to learn to work as a node in a network, not just a king in a castle, because kings don’t last anymore.

So which way is forward. The priority now needs to be deciding what sort of future do we want. Not what sort of past do we want to escape. The 21st century sees many communities emerging. They are hyper connected, transnational, multicultural, heavily interdependent, heavily specialised, rapidly changing and disconnected from their geopolitical roots. Some people see that as a reason to move away from having geopolitically formed states. Personally I believe there will always be a role for a geographic state because I need a way to scale a quality of life for my family along with my fellow citizens and neighbours. But what does that mean in an international sense. Are my rights as a human being being realised in a transnational sense. There are some really interesting questions about the needs of users beyond the individual services that we deliver, particularly when you look in a transnational way.

So a lot of these assumptions have become like a rusty anchor that kept us in place in high tide, but are drawing us to a dangerous reef as to water lowers. We need to figure out how to float on the water without rusty anchors to adapt to the tides of change.

There are a lot of pressures that are driving these changes of course. We are all feeling those pressures, those of us that are working in government. There’s the pressure of changing expectations, of history, from politics and the power shift. The pressure of the role of government in the 21st century. Pressure is a wonderful thing as it can be a catalyst of change, so we shouldn’t shy away from pressure, but recognising that we’re under pressure is important.

So let’s explore some of those power shifts and then what role could government play moving forward.

Paradigm #1: central to distributed. This is about that shift in power, the independence movements and the internet. It is something people talk about but don’t necessarily apply to their work. Governments will talk about wanting to take a more distributed approach but followup with setting up “my” website expecting everyone to join or do something. How about everyone come to “my” office or create “my” own lab. Distributed, when you start to really internalise what that means, if different. I was lucky as I forged a lot of my assumptions and habits of working when I was involved in the Open Source community, and the Open Source community has a lot of lessons for rest of society because it is on the bleeding edge of a lot of these paradigm shifts. So working in a distributed way is to assume that you are not at the centre, to assume that you’re not needed. To assume that if you make yourself useful that people will rely on you, but also to assume that you rely on others and to build what you do in a way that strengthens the whole system. I like to talk about it as “Gov as a Platform”, sometimes that is confusing to people so let’s talk about it as “Gov as an enabler”. It’s not just government as a central command and controller anymore because the moment you create a choke point, people route around it. How do we become a government as an enabler of good things, and how can we use other mechanisms to create the controls in society. Rather than try to protect people from themselves, why not enable people to protect themselves. There are so many natural motivations in the community, in industry, in the broader sector that we serve, that we can tap into but traditionally we haven’t. Because traditionally we saw ourselves as the enforcer, as the one to many choke point. So working in a distributed way is not just about talking the talk, it’s about integrated it into the way we think.

Some other aspects of this include localised to globalised, keeping in mind that large multinational companies have become quite good at jurisdiction shopping for improvements of profits, which you can’t say is either a good or bad thing, it’s just a natural thing and how they’re naturally motivated. But citizens are increasingly starting to jurisdiction shop too. So I would suggest a role for government in the 21st century would be to create the best possible quality of life for people, because then you’ll attract the best from around the world.

The second part of central to distributed is simple to complex. I have this curve (on the slide) which shows green as complexity and red as government’s response to user needs. The green climbs exponentially whilst the red is pretty linear, with small increases or decreases over time, but not an exponential response by any means. Individual needs are no longer heavily localised. They are subject to local, national, transnational complexities with every extra complexity compounded, not linear. So the increasing complexities in people’s lives, and the obligations, taxation, services and entitlements, everything is going up. So there is a delta forming between what government can directly do, and what people need. So again I contend that the opportunity here particularly for the public sector is to actually be an enabler for all those service intermediaries – the for profit, non profit, civic tech – to help them help themselves, help them help their customers, by merit of making government a platform upon which they can build. We’ve had a habit and a history of creating public infrastructure, particularly in Australia, in New Zealand, in Canada, we’re been very good at building public infrastructure. Why have we not focused on digital infrastructure? Why do we see digital infrastructure as something that has to be cost recovered to be sustainable when we don’t have to do cost recovery for every thing public road. I think that looking at the cost benefits and value creation of digital public infrastructure needs to be looks at in the same way, and we need to start investing in digital public infrastructure.

Next paradigm shift, analog to digital, or slow to very fast. I like to joke that we use lawyers as modems. If you think about regulation and policy, we write it, it is translated by a lawyer or drafter into regulation or policy, it is then translated by a lawyer or drafter or anyone into operational systems, business systems, helpdesk systems or other systems in society. Why wouldn’t we make our regulation as code? The intent of our regulation and our legislative regimes available to be directly consumed (by the systems) so that we can actually speed up, automate, improve consistency of application through the system, and have a feedback loop to understand whether policy changes are having the intended policy effect.

There are so many great things we can do when we start thinking about digital as something new, not just digitising an analog process. Innovation too long was interpreted as a digitisation of a process, basic process improvements. But real digitisation should a a transformation where you are changing the thing to better achieve the purpose or intent.

The next paradigm is scarcity to surplus. I think this is critical. We have a lot of assumptions in our systems that assume scarcity. Why do we still have so many of our systems assume scarcity when surplus is the opportunity. Between 3D printing and nanotech, we could be deconstructing and reconstructing new materials to print into goods and food and yet a large inhibitor of 3D printing progress is copyright. So the question I have for you is do we care more about an 18h century business model or do we care about solving the problems of our society. We need to make these choices. If we have moved to an era of surplus but we are getting increasing inequality, perhaps the systems of distribution are problematic? Perhaps in assuming scarcity we are protecting scarcity for the few at the cost of the many.

Next paradigm is normative to formative, “please comply”. For the last hundred years in particular we have perfected the art of broadcasting images of normal into our houses, particularly with radio and television. We have the concept of set a standard or rule and if you don’t follow we’ll punish you, so a lot of culture is about compliance in society. Compliance is important for stability, but blind compliance can create millstones. A formative paradigm is about not saying how it is but in exploring where you want to go. In the public service we are particularly good at compliance culture but I suggest that if we got more people thinking formatively, not just change for changes sake, but bringing people together on their genuinely shared purpose of serving the public, then we might be able to take a more formative approach to doing the work we do for the betterment of society rather than ticking the box because it is the process we have to follow. Formative takes us away from being consumers and towards being makers. As an example, the most basic form of normative human behaviour is in how we see and conform to being human. You are either normal, or you are not, based on some externally projected vision of normal. But the internet has shown us that no one is normal. So embracing that it is through our difference we are more powerful and able to adapt is an important part of our story and culture moving forward. If we are confident to be formative, we can always trying to create a better world whilst applying a critical eye to compliance so we don’t comply for compliance sake.

Now on the back of these paradigm shifts, I’d like to briefly about the future. I spoke about the opportunity through surplus with 3D printing and nanotech to address poverty and hunger. What about the opportunities of rockets for domestic travel? It takes half an hour to get into space, an hour to traverse the world and half an hour down which means domestic retail transport by rocket is being developed right now which means I could go from New Zealand to Canada to work for the day and be home for tea. That shift is going to be enormous in so many ways and it could drive real changes in how we see work and internationalism. How many people remember Total Recall? The right hand picture is a self driving car from a movie in the 90s and is becoming normal now. Interesting fact, some of the car designs will tint the windows when they go through intersections because the passengers are deeply uncomfortable with the speed and closeness of self driving cars which can miss each other very narrowly compared to human driving. Obviously there are opportunities around AI, bots and automation but I think where it gets interesting when we think about opportunities of the future of work. We are still working on industrial assumptions that the number of hours that we have is a scarcity paradigm and I have to sell the number of hours that I work, 40, 50, 60 hours. Why wouldn’t we work 20 hours a week at a higher rate to meet our basic needs? Why wouldn’t we have 1 or 2 days a week where we could contribute to our civic duties, or art, or education. Perhaps we could jump start an inclusive renaissance, and I don’t mean cat pictures. People can’t thrive if they’re struggling to survive and yet we keep putting pressure on people just to survive. Again, we are from countries with quite strong safety nets but even those safety nets put huge pressure, paperwork and bureaucracy on our most vulnerable just to meet their basic needs. Often the process of getting access to the services and entitlements is so hard and traumatic that they can’t, so how do we close that gap so all our citizens can move from survival to thriving.

The last picture is a bit cheeky. A science fiction author William Gibson wrote Johnny Pneumonic and has a character in that book called Jones, a cyborg dolphin to sniff our underwater mines in warfare. Very dark, but the interesting concept there is in how Jones was received after the war: “he was more than a dolphin, but from another dolphin’s point of view he might have seemed like something less.” What does it mean to be human? If I lose a leg, right now it is assumed I need to replace that leg to be somehow “whole”. What if I want 4 legs. The human brain is able to adapt to new input. I knew a woman who got a small sphere filled with mercury and a free floating magnet in her finger, and the magnet spins according to frequency and she found over a short period of time she was able to detect changes in frequency. Why is that cool and interesting? Because the brain can adapt to foreign, non evolved input. I think that is mind blowing. We have the opportunity to augment our selves not to just conform to normal or be slightly better, faster humans. But we can actually change what it means to be human altogether. I think this will be one of the next big social challenges for society but because we are naturally so attracted to “shiny”, I think that discomfort will pass within a couple of generations. One prediction is that the normal Olympics has become boring and that we will move into a transhuman olympics where we take the leash off and explore the 100m sprint with rockets, or judo with cyborgs. Where the interest goes, the sponsorship goes, and more professional athletes compete. And what’s going to happen if your child says they want to be a professional transhuman olympian and that they will add wings or remove their legs for their professional career, to add them (or not) later? That’s a bit scary for many but at the same time, it’s very interesting. And it’s ok to be uncomfortable, it’s ok to look at change, be uncomfortable and ask yourself “why am I uncomfortable?” rather than just pushing back on discomfort. It’s critical more than ever, particularly in the public service that we get away from this dualistic good or bad, in or out, yours or mine and start embracing the grey.

So what’s the role of government in all this, in the future. Again these are just some thoughts, a conversation starter.

I think one of our roles is to ensure that individuals have the ability to thrive. Now I acknowledge I’m very privileged to have come from a social libertarian country that believe this, where people broadly believe they want their taxes to go to the betterment of society and not all countries have that assumption. But if we accept the idea that people can’t thrive if they can’t survive, then our baseline quality of life if you assume an individual starts from nothing with no privilege, benefits or family, provided by the state, needs to be good enough for the person to be able to thrive. Otherwise we get a basic structural problem. Part of that is becoming master buildings again, and to go to the Rawl’s example from Alistair before, we need empathy in what we do in government. The amount of times we build systems without empathy and they go terribly wrong because we didn’t think about what it would be like to be on the other side of that service, policy or idea. User centred design is just a systematisation of empathy, which is fantastic, but bringing empathy into everything we do is very important.

Leadership is a very important role for government. I think part of our role is to represent the best interests of society. I very strongly feel that we have a natural role to serve the public in the public sector, as distinct from the political sector (though citizens see us as the same thing). The role of a strong, independent public sector is more important than ever in a post facts “fake news” world because it is one of the only actors on the stage that is naturally motivated, naturally systemically motivated, to serve the best interests of the public. That’s why open government is so important and that’s why digital and open government initiatives align directly.

Because open with digital doesn’t scale, and digital without open doesn’t last.

Stability, predictability and balance. It is certainly a role of government to create confidence in our communities, confidence creates thriving. It is one thing to address Maslov’s pyramid of needs but if you don’t feel confident, if you don’t feel safe, then you still end up behaving in strange and unpredictable ways. So this is part of what is needed for communities to thrive. This relates to regulation and there is a theory that regulation is bad because it is hard. I would suggest that regulation is important for the stability and predictability in society but we have to change the way we deliver it. Regulation as code gets the balance right because you can have the settings and levers in the economy but also the ability for it to be automated, consumable, consistent, monitored and innovative. I imagine a future where I have a personal AI which I can trust because of quantum cryptography and because it is tethered in purpose to my best interests. I don’t have to rely on whether my interests happen to align with the purpose of a department, company or non-profit to get the services I need because my personal bot can figure out what I need and give me the options for me to make decisions about my life. It could deal with the Government AI to figure out the rules, my taxation, obligations, services and entitlements. Where is the website in all that? I ask this because the web was a 1990s paradigm, and we need more people to realise and plan around the idea that the future of service delivery is in building the backend of what we do – the business rules, transactions, data, content, models – in a modular consumable so we can shift channels or modes of delivery whether it is a person, digital service or AI to AI interaction.

Another role of government is in driving the skills we need for the 21st century. Coding is critical not because everyone needs to code (maybe they will) but more than that coding teaches you an assumption, an instinct, that technology is something that can be used by you, not something you are intrinsically bound to. Minecraft is the saviour of a generation because all those kids are growing up believing they can shape the world around them, not have to be shaped by the world around them. This harks back to the normative/formative shift. But we also need to teach critical thinking, teach self awareness, bias awareness, maker skills, community awareness. It has been delightful to move to New Zealand where they have a culture that has an assumed community awareness.

We need of course to have a strong focus on participatory democracy, where government isn’t just doing something to you but we are all building the future we need together. This is how we create a multi-processor world rather than a single processor government. This is how we scale and develop a better society but we need to move beyond “consultation” and into actual co-design with governments working collaboratively across the sectors and with civil society to shape the world.

I’ll finish on this note, government as an enabler, a platform upon which society can build. We need to build a way of working that assumes we are a node in the network, that assumes we have to work collaboratively, that assumes that people are naturally motivated to make good decisions for their life and how can government enable and support people.

So embrace the tipping point, don’t just react. What future do you want, what society do you want to move towards? I guess I’ve got to a point in my life where I see everything as a system and if I can’t connect the dots between what I’m doing and the purpose then I try to not do that thing. The first public service job I had I got in and automated a large proportion of the work within a couple of weeks and then asked for data.gov.au, and they gave it to me because I was motivated to make it better.

So I challenge you to be thinking about this every day, to consider your own assumptions and biases, to consider whether you are being normative or formative, to evaluate whether you are being iterative or transformative, to evaluate whether you are moving away from something or towards something. And to always keep in mind where you want to be, how you are contributing to a better society and to actively leave behind those legacy ideas that simply don’t serve us anymore.

Categories: thinktime

Ten Extras for Great API Documentation

a list apart - Wed 08th Nov 2017 02:11

If you manage to create amazing API documentation and ensure that developers have a positive experience implementing your API, they will sing the praises of your product. Continuously improving your API documentation is an investment, but it can have a huge impact. Great documentation builds trust, differentiates you from your competition, and provides marketing value.

I’ve shared some best practices for creating good API documentation in my article “The Ten Essentials for Good API Documentation.” In this article, I delve into some research studies and show how you can both improve and fine-tune different aspects of your API documentation. Some of these extras, like readability, are closer to essentials, while others are more of a nice-to-have, like personality. I hope they give you some ideas for building the best possible docs for your product.

Overview page

Whoever visits your API documentation needs to be able to decide at first glance whether it is worth exploring further. You should clearly show:

  • what your API offers (i.e., what your products do);
  • how it works;
  • how it integrates;
  • and how it scales (i.e., usage limits, pricing, support, and SLAs).
Spotify’s API documentation clearly states what the API does and how it works, and it provides links to guides and API references organized in categories.

An overview page targets all visitors, but it is especially helpful for decision-makers. They have to see the business value: explain to them directly why a company would want to use your API.

Developers, on the other hand, want to understand the purpose of the API and its feature set, so they tend to turn to the overview page for conceptual information. Show them the architecture of your API and the structure of your docs. Include an overview of different components and an introduction into the request-response behavior (i.e., how to integrate, how to send requests, and how to process responses). Provide information on the platforms on which the API is running (e.g., Java) and possible interactions with other platforms.

As the study “The role of conceptual knowledge in API usability” found, without conceptual knowledge, developers struggle to formulate effective queries and to evaluate the relevance or meaning of content they find. That’s why API documentation should not only include detailed examples of API use, but also thorough introductions to the concepts, standards, and ideas in an API’s data structures and functionality. The overview page can be an important component to fulfill this role.

Braintree’s API overview page provides a clear overview of their SDKs, along with a visual step-by-step explanation of how their API works. Examples

For some developers, examples play a more important role in getting started with an API than the explanations of calls and parameters.

A recent study, “Application Programming Interface Documentation—What Do Software Developers Want?,” explored how software developers interact with API documentation: what their goals are, how they learn, where they look for information, and how they judge the quality of API docs.

The role of examples

The study found that after conducting an initial overview of what the API does and how it works, developers approach learning about the API in two distinct ways: some follow a top-down approach, where they try to build a thorough understanding of the API before starting to implement specific use cases, while others prefer to follow a bottom-up approach, where they start coding right away.

This latter group has a code-oriented learning strategy; they start learning by trying and extending code examples. Getting into an API is most often connected with a specific task. They look for an example that has the potential of serving as a basis to solve their problem, but once they’ve found the solution they were looking for, they usually stop learning.

Examples are essential for code-oriented learners, but all developers benefit from them. The study showed that developers often trust examples more than documentation, because if they work, they can’t be outdated or wrong. Developers often struggle with finding out where to start and how to begin with a new API—examples can become good entry points in this case. Many developers can grasp information more easily from code than text, and they can re-use code in examples for their own implementation. Examples also play other roles that are far from obvious: they automatically convey information about dependencies and prerequisites, they help identify relevant sections in the documentation when developers are scanning the page, and they intuitively show developers how code that uses the API should look.

Improve your examples

Because examples are such a crucial component in API documentation, better examples mean better docs.

To ensure the quality of your examples, they should be complete, be programmed professionally, and work correctly. Because examples convey so much more than the actual use case, make sure to follow the style guidelines of the respective community and show best-practice approaches. Add brief, informative explanations; although examples can be self-explanatory, comments included with sample code help comprehension.

Add concrete, real-life examples whenever you can. If you don’t have real examples, make sure they at least look real: use realistic variable names and functions instead of abstract ones.

When including examples, you have a variety of formats and approaches to choose from: auto-generated examples, sample applications, client libraries, and examples in multiple languages.

Auto-generated examples

Autodoc tools like Swagger Codegen and API Blueprint automatically generate documentation from your source code and keep it up-to-date as the code changes. Use them to generate reference libraries and sample code snippets, but be aware that what you produce this way is only skeleton—not fleshed out—documentation. You will still have to add explanations, conceptual information, quick-start guides, and tutorials, and you should still pay attention to other aspects like UX and good-quality copy.

On the Readme blog, they explore autodoc tools and their limitations in more depth through a couple of real-world examples.

Sample applications

Working applications that use the API are a great way to show how everything works together and how the API integrates with different platforms and technologies. They are different than sample code snippets, because they are stand-alone solutions that show the big picture. As such, they are helpful to developers who would like to see how a full implementation works and to have an overall understanding of how everything in the API ties together. On the other hand, they are real products that showcase the services and quality of your API to decision makers. Apple’s iOS Developer Portal offers buildable, executable source examples of how to accomplish a task using a particular technology in a wide variety of categories.   

Client libraries

Client libraries are chunks of code that developers can add to their own development projects. They are usually available in various programming languages, and cover basic functionality for an application to be able to interact with the API. Providing them is an extra feature that requires ongoing investment from the API provider, but doing so helps developers jump-start their use of the API. GitHub follows the practical approach of offering client libraries for the languages that are used the most with their API, while linking to unsupported, community-built libraries written in other, less popular languages.

Examples in multiple languages

APIs are platform- and language-independent by nature. Developers can use an API’s services with the language of their choice, but this means good documentation should cover at least the most popular languages used with that particular API (e.g., C#, Java, JavaScript, Go, Objective-C, PHP, Python, Ruby, and Swift). Not only should you provide sample code and sample applications in different languages, but also these samples should reflect the best-practice approach for each language.

Usability

API documentation is a tool that helps developers and other stakeholders do their job. You should adapt it to the way people use it, and make it as easy to use as possible. Consider the following factors:

  • Copy and paste: Developers copy and paste code examples to use them as a starting point for their own implementation. Make this process easier with either a copy button next to relevant sections or by making sections easy to highlight and copy.
  • Sticky navigation: When implemented well, fixing the table of contents and other navigation to the page view can prevent users from getting lost and having to scroll back up.
  • Clicking: Minimize clicking by keeping related topics close to each other.
  • Language selector: Developers should be able to see examples in the language of their choice. Put a language selector above the code examples section, and make sure the page remembers what language the user has selected.
  • URLs: Single page views can result in very long pages, so make sure people can link to certain sections of the page. If, however, a single page view doesn’t work for your docs, don’t sweat it: just break different sections into separate pages. .main-content figure figcaption { display: block;margin: 12px 0;text-align: center;font-size: 14px;line-height: 24px;font-style: italic;font-family: georgia,serif; } .main-content figure { margin-top: 36px;margin-bottom: 36px;overflow: hidden; } Great usability: Stripe’s API documentation changes the URL dynamically as you scroll through the page.

    Another best practice from Stripe: the language selector also changes the URL, so URLs link to the right location in the right language.

  • Collaboration: Consider allowing users to contribute to your docs. If you see your users edit your documentation, it indicates there might be room for improvement—in those parts of your docs or even in your code. Additionally, your users will see that issues are addressed and the documentation is frequently updated. One way to facilitate collaboration is to host your documentation on GitHub, but be aware that this will limit your options of interactivity, as GitHub hosts static files.

Interactivity

Providing an option for users to interact with your API through the documentation will greatly improve the developer experience and speed up learning.

First, provide a working test API key or, even better, let your users log in to your documentation site and insert their own API key into sample commands and code. This way they can copy, paste, and run the code right away.

As a next step, allow your users to make API calls directly from the site itself. For example, let them query a sample database, modify their queries, and see the results of these changes.

A more sophisticated way to make your documentation more interactive is by providing a sandbox—a controlled environment where users can test calls and functions against known resources, manipulating data in real-time. Developers learn through the experience of interacting with your API in the sandbox, rather than by switching between reading your docs and trying out code examples themselves. Nordic APIs explains the advantages of sandboxing, discusses the role of documentation in a sandboxed environment, and shows a possible implementation. To see a sandbox in action, try out the one on Dwolla’s developer site.

Help

The study exploring how software developers interact with API documentation also explored how developers look for help. In a natural work environment, they usually turn to their colleagues first. Then, however, many of them tend to search the web for answers instead of consulting the official product documentation. This means you should ensure your API documentation is optimized for search engines and will turn up relevant results in search queries.

To make sure you have the necessary content available for self-support, include FAQs and a well-organized knowledge base. For quick help and human interaction, provide a contact form, and—if you have the capacity—a help-desk solution right from your docs, e.g., a live chat with support staff.

The study also pointed at the significant role Stack Overflow plays: most developers interviewed mentioned the site as a reliable source of self-help. You can also support your developers’ self-help efforts and sense of community by adding your own developer forum to your developer portal or by providing an IRC or Slack channel.

Changelog

As with all software, APIs change and are regularly updated with new features, bug fixes, and performance improvements.

When a new version of your API comes out, you have to inform the developers working with your API about the changes so they can react to them accordingly. A changelog, also called release notes, includes information about current and previous versions, usually ordered by date and version number, along with associated changes.

If there are changes in a new version that can break old use of an API, put warnings on top of relevant changelogs, even on top of your release notes page. You can also bring attention to these changes by highlighting or marking them permanently.

To keep developers in the loop, offer an RSS feed or newsletter subscription where they can be notified of updates to your API.

Besides the practical aspect, a changelog also serves as a trust signal that the API and its documentation are actively maintained, and that the information included is up-to-date.

Analytics and feedback

You can do some research by getting to know your current and potential clients, talking to people at conferences, exploring your competition, and even conducting surveys. Still, you will have to go with a lot of assumptions when you first build your API docs.

When your docs are up, however, you can start collecting usage data and feedback to learn how you can improve them.

Find out about the most popular use cases through analytics. See which endpoints are used the most and make sure to prioritize them when working on your documentation. Get ideas for tutorials, and see which use cases you haven’t covered yet with a step-by-step walkthrough from developer community sites like Stack Overflow or your own developer forums. If a question regarding your API pops up on these channels and you see people actively discussing the topic, you should check if it’s something that you need to explain in your documentation.

Collect information from your support team. Why do your users contact them? Are there recurring questions that they can’t find answers for in the docs? Improve your documentation based on feedback from your support team and see if you have been successful: have users stopped asking the questions you answered?

Listen to feedback and evaluate how you could improve your docs based on them. Feedback can come through many different channels: workshops, trainings, blog posts and comments about your API, conferences, interviews with clients, or usability studies.

Readability

Readability is a measure of how easily a reader can understand a written text—it includes visual factors like the look of fonts, colors, and contrast, and contextual factors like the length of sentences, wording, and jargon. People consult documentation to learn something new or to solve a problem. Don’t make the process harder for them with text that is difficult to understand.

While generally you should aim for clarity and brevity from the get-go, there are some specific aspects you can work on to improve the readability of your API docs.

Audience: Expect that not all of your users will be developers and that even developers will have vastly different skills and background knowledge about your API and business domain. To cater to the different needs of different groups in your target audience, explain everything in detail, but provide ways for people already familiar with the functionality to quickly find what they are looking for, e.g., add a logically organized quick reference.

Wording: Explain everything as simply as you can. Use short sentences, and make sure to be consistent with labels, menu names, and other textual content. Include a clear, straightforward explanation for each call. Avoid jargon if possible, and if not, link to domain-related definitions the first time you use them. This way you can make sure that people unfamiliar with your business domain get the help they need to understand your API.

Fonts: Both the font size and the font type influence readability. Have short section titles and use title case to make it easier to scan them. For longer text, use sans serif fonts. In print, serif fonts make reading easier, but online, serif characters can blur together. Opt for fonts like Arial, Helvetica, Trebuchet, Lucida Sans, or Verdana, which was designed specifically for the web. Contrast plays an important role as well: the higher the contrast, the easier the text is to read. Consider using a slightly larger font size and different typeface for code than for text to help your users’ visual orientation when switching back and forth between their code editor and your documentation.

Structure: API documentation should cater to newcomers and returning visitors alike (e.g., developers debugging their implementation). A logical structure that is easy to navigate and that allows for quick reference works for both. Have a clear table of contents and an organized list of resources, and make sections, subsections, error cases, and display states directly linkable.

Great usability: Linkability demonstrated on Stripe’s API documentation.

Scannability: As Steve Krug claims in his book about web usability, Don’t Make Me Think, one of the most important facts about web users is that they don’t read, they scan. To make text easier to scan, use short paragraphs, highlight relevant keywords, and use lists where applicable.

Accessibility: Strive to make your API docs accessible to all users, including users who access your documentation through assistive technology (e.g., screen readers). Be aware that screen readers may often struggle with reading code and may handle navigation differently, so explore how screen readers read content. Learn more about web accessibility, study Web Content Accessibility Guidelines, and do your best to adhere to them.

Personality

You’ve worked hard to get to know your audience and follow best practices to leave a good impression with your API docs. Now, as a finishing touch, you can make sure your docs “sound” and look in tune with your brand.

Although API documentation and technical writing in general don’t provide much room for experimentation in tone and style, you can still instill some personality into your docs:

  • Use your brand book and make sure your API docs follow it to the letter.
  • A friendly tone and simple style can work wonders. Remember, people are here to learn about your API or solve a problem. Help them by talking to them in a natural manner that is easy to understand.
  • Add illustrations that help your readers understand any part of your API. Show how different parts relate to each other; visualize concepts and processes.
  • Select your examples carefully so that they reflect on your product the way you want them to. Playful implementations of your API will create a different impression than more serious or enterprise use cases. If your brand allows, you can even have some fun with examples (e.g., funny examples and variable names), but don’t go overboard.
  • You can insert some images (beyond illustrations) where applicable, but make sure they add something to your docs and don’t distract readers.
Think developer portal—and beyond

Although where you draw the line between API documentation and developer portal is still up for debate, most people working in technical communication seem to agree that a developer portal is an extension of API documentation. Originally, API documentation meant strictly the reference docs only, but then examples, tutorials, and guides for getting started became part of the package; yet we still called them API docs. As the market for developer communication grows, providers strive to extend the developer experience beyond API documentation to a full-fledged developer portal.

In fact, some of the ideas discussed above—like a developer forum or sandboxes—already point in the direction of building a developer portal. A developer portal is the next step in developer communication, where besides giving developers all the support they need, you start building a community. Developer portals can include support beyond docs, like a blog or videos. If it fits into the business model, they can also contain an app store where developers submit their implementations and the store provides a framework for them to manage the whole sales process. Portals connected to an API often also contain a separate area with landing pages and showcases where you can directly address other stakeholders, such as sales and marketing.

Even if you’re well into building your developer portal, you can still find ways to learn more and extend your reach. Attend and present at conferences like DevRelCon, Write The Docs or API The Docs to get involved in developer relations. Use social media: tweet, join group discussions, or send a newsletter. Explore the annual Stack Overflow Developer Survey to learn more about your main target audience. Organize code and documentation sprints, trainings, and workshops. Zapier has a great collection of blogs and other resources you can follow to keep up with the ever-changing API economy—you will surely find your own sources of inspiration as well.

I hope “The Ten Essentials for Good API Documentation” and this article gave you valuable insight into creating and improving your API documentation and inspire you to get started or keep going.

Categories: thinktime

Disastorino

Seth Godin - Tue 07th Nov 2017 19:11
Elections are the only place where marketers try to get fewer people to buy what's being sold. In many elections in the US, fewer than half the population votes. Which means, of course, that in most elections, not only doesn't...        Seth Godin
Categories: thinktime

James Bromberger: Web Security 2017

Planet Linux Australia - Tue 07th Nov 2017 03:11

I started web development around late 1994. Some of my earliest paid web work is still online (dated June 1995). Clearly, that was a simpler time for content! I went on to be ‘Webmaster’ (yes, for those joining us in the last decade, that was a job title once) for UWA, and then for Hartley Poynton/JDV.com at time when security became important as commerce boomed online.

At the dawn of the web era, the consideration of backwards compatibility with older web clients (browsers) was deemed to be important; content had to degrade nicely, even without any CSS being applied. As the years stretched out, the legacy became longer and longer. Until now.

In mid-2018, the Payment Card Industry (PCI) Data Security Standard (DSS) 3.2 comes into effect, requiring card holder environments to use (at minimum) TLS 1.2 for the encrypted transfer of data. Of course, that’s also the maximum version typically available today (TLS 1.3 is in draft 21 at this point in time of writing). This effort by the PCI is forcing people to adopt new browsers that can do the TLS 1.2 protocol (and the encryption ciphers that permits), typically by running modern/recent Chrome, Firefox, Safari or Edge browsers. And for the majority of people, Chrome is their choice, and the majority of those are all auto-updating on every release.

Many are pushing to be compliant with the 2018 PCI DSS 3.2 as early as possible; your logging of negotiated protocols and ciphers will show if your client base is ready as well. I’ve already worked with one government agency to demonstrate they were ready, and have already helped disable TLS 1.0 and 1.1 on their public facing web sites (and previously SSL v3). We’ve removed RC4 ciphers, 3DES ciphers, and enabled ephemeral key ciphers to provide forward secrecy.

Web developers (writing Javascript and using various frameworks) can rejoice — the age of having to support legacy MS IE 6/7/8/9/10 is pretty much over. None of those browsers support TLS 1.2 out of the box (IE 10 can turn this on, but for some reason, it is off by default). This makes Javascript code smaller as it doesn’t have to have conditional code to work with the quirks of those older clients.

But as we find ourselves with modern clients, we can now ask those clients to be complicit in our attempts to secure the content we serve. They understand modern security constructs such as Content Security Policies and other HTTP security-related headers.

There’s two tools I am currently using to help in this battle to improve web security. One is SSLLabs.com, the work of Ivan Ristić (and now owned/sponsored by Qualys). This tool gives a good view of the encryption in flight (protocols, ciphers), chain of trust (certificate), and a new addition of checking DNS records for CAA records (which I and others piled on a feature request for AWS Route53 to support). The second tool is Scott Helm’s SecurityHeaders.io, which looks at the HTTP headers that web content uses to ask browsers to enforce security on the client side.

There’s a really important reason why these tools are good; they are maintained. As new recommendations on ciphers, protocols, signature algorithms or other actions become recommended, they’re updated on these tools. And these tools are produced by very small, but agile teams — like one person teams, without the bureaucracy (and lag) associated with large enterprise tools. But these shouldn’t be used blindly. These services make suggestions, and you should research them yourselves. For some, not all the recommendations may meet your personal risk profile. Personally, I’m uncomfortable with Public-Key-Pins, so that can wait for a while — indeed, Chrome has now signalled they will drop this.

So while PCI is hitting merchants with their DSS-compliance stick (and making it plainly obvious what they have to do), we’re getting a side-effect of having a concrete reason for drawing a line under where our backward compatibility must stretch back to, and the ability to have the web client assist in ensure security of content.

Categories: thinktime

This is post 7,000

Seth Godin - Mon 06th Nov 2017 21:11
[actually, it's more than that, but the previous incarnations of this blog are lost to the fogs of time] Delivered free, daily, for decades. You can subscribe at no cost by email, by following this blog on Twitter or Facebook,...        Seth Godin
Categories: thinktime

Cheap symbolism

Seth Godin - Sun 05th Nov 2017 20:11
The engineering mindset tells us that all that matters is what's under the surface, the measurable performance. Designers know that perception is at least as valuable. Symbolic acts are rarely cheap or wasted if they work. Because we're story-telling creatures,...        Seth Godin
Categories: thinktime

The overflowing outbox

Seth Godin - Sat 04th Nov 2017 19:11
Deadlines are vitamins for creativity. If you've got too much in progress, too much of a buffer, too many items ready to go, it's easy to slip back to complacency. Without the feeling of imminent, it's easier to hide. If...        Seth Godin
Categories: thinktime

OpenSTEM: This Week in HASS – term 4, week 5

Planet Linux Australia - Sat 04th Nov 2017 13:11
Halfway through the last term of the year already! This week our youngest students consider museums as a place to learn about the past. Slightly older students are learning about the states and territories of Australia, as well as their representative birds and animals. Older students are in throes of their class election campaign, preparing […]
Categories: thinktime

The real law of averages

Seth Godin - Fri 03rd Nov 2017 19:11
If you want to raise the standards of any group, improving the top of the heap isn't nearly as effective as focusing your effort on the base instead. Simple example: Getting a Prius to go from 50 miles per gallon...        Seth Godin
Categories: thinktime

Russell Coker: Work Stuff

Planet Linux Australia - Fri 03rd Nov 2017 17:11

Does anyone know of a Linux support company that provides 24*7 support to Ruby and PHP applications? I have a client that is looking for such a company.

Also I’m looking for more consulting work. If anyone knows of an organisation that needs some SE Linux consulting, or support for any of the FOSS software I’ve written then let me know. I take payment by Paypal and Bitcoin as well as all the usual ways. I can make a private build of any of my FOSS software to suit your requirements or if you want features that could be used by other people (and don’t conflict with the general use cases) I can add them on request. Small changes start at $100.

Related posts:

  1. Debian Work and Upstream Steve Kemp writes about security issues with C programs [1]....
  2. Getting Work in Another Country Often there are possibilities to earn more money or gain...
  3. Increasing Efficiency through Less Work I have just read an interesting article titled Why Crunch...
Categories: thinktime

What the Failure of New Coke Can Teach Us About User Research And Design

a list apart - Thu 02nd Nov 2017 23:11

In the late 1970s, Pepsi was running behind Coca-Cola in the competition to be the leading cola. But then Pepsi discovered that in blind taste tests, people actually preferred the sweeter taste of Pepsi. To spread the word, Pepsi ran a famous advertising campaign, called the Pepsi Challenge, which showed people tasting the two brands of cola while not knowing which was which. They chose Pepsi every time.

As Pepsi steadily gained market share in the early 1980s, Coca-Cola ran the same test and found the same result—people simply preferred Pepsi when tasting the two side by side. So, after conducting extensive market research, Coca-Cola’s solution was to create a sweeter version of its famous cola—New Coke. In taste tests, people preferred the new formula of Coke to both the regular Coke formula and to Pepsi.

Despite this success in tests, when the company brought New Coke to market, customers revolted. New Coke turned out to be one of the biggest blunders in marketing history. Within months, Coke returned its original formula—branded as “Coca-Cola Classic”—to the shelves.

In the end, sales showed that people preferred Coke Classic. But Coca-Cola’s research predicted just the opposite. So what went wrong?

The tests had people drink one or two sips of each cola in isolation and then decide which they preferred based on that. The problem is, that’s not how people drink cola in real life. We might have a can with a meal. And we almost never drink just one or two sips. User research is just as much about the way the research is conducted as it is about the product being researched.

For the purposes of designing and researching digital services and websites, the point is that people can behave differently in user research than they do in real life. We need to be conscious of the way we design and run user research sessions and the way we interpret the results to take real-life behavior into account—and avoid interpretations that lead to a lot of unnecessary work and a negative impact on the user experience.

To show how this applies to web design, I’d like to share three examples taken from a project I worked on. The project was for a government digital service that civil servants use to book and manage appointments. The service would replace a third-party booking system called BookingBug. We were concerned with three user needs:

  • booking an appointment;
  • viewing the day’s appointments;
  • and canceling an appointment.
Booking an appointment

We needed to give users a way to book an appointment, which consisted of selecting a location, an appointment type, and a person to see. The order of these fields matters: not all appointment types can be conducted at every location, and, not all personnel are trained to conduct every appointment type.

The first iteration of the booking journey, with three select boxes in one page.

Our initial design had three select boxes in one page. Selecting an option in the first select box would cause the values in the subsequent boxes to be updated, but because it was just a prototype we didn’t build this into the test. Users selected an option from each of the select boxes easily and quickly. But afterwards, we realized that the test didn’t really reflect how the interface would actually work.

In reality, the select boxes would need to be updated dynamically with AJAX, which would slow things down drastically and affect the overall experience. We would also need a way to indicate that something was loading—like a loading spinner. This feedback would also need to be perceivable to visually-impaired users relying on a screen reader.

That’s not all: each select box would need to have a submit button because submitting a form onchange is an inclusive design anti-pattern. This would also cover scenarios where there is a JavaScript failure, otherwise, users would be left with a broken interface. With that said, we weren’t thrilled with the idea of adding more submit buttons. One call to action is often simpler and clearer.

As mentioned earlier, the order in which users select options matters, because completing each step causes the subsequent steps to be updated. For production, if the user selected options in the wrong order, things could break. However, the prototype didn’t reflect this at all—users could select anything, in any order, and proceed regardless.

Users loved the prototype, but it wasn’t something we could actually give them in the end. To test this fairly and realistically, we would need to do a lot of extra work. What looked innocently like a simple prototype gave us misleading results.

Our next iteration followed the One Thing Per Page pattern; we split out each form field into a separate screen. There was no need for AJAX, and each page had a single submit button. This also stopped users from answering questions in the wrong order. As there was no longer a need for AJAX, the related accessibility considerations went away too.

The second iteration of the booking journey, with a separate page for each step.

This tested really well. The difference was that we knew the prototype was realistic, meaning users would get a similar experience when the feature went into production.

Viewing the day’s appointments

We needed to give users a way to view their schedule. We laid out the appointments in a table, where each row represented an appointment. Any available time was demarcated by the word “Available.” Appointments were linked, but available times were not.

The schedule page to view the day’s appointments.

In the first round of research, we asked users to look at the screen and give feedback. They told us what they liked, what they didn’t, and what they would change. Some participants told us they wanted their availability to stand out more. Others said they wanted color-coded appointment types. One participant even said the screen looked boring.

During the debrief, we realized they wanted color-coded appointments because BookingBug (to which they had become accustomed) had them. However, the reason BookingBug used color for appointments was that the system’s layout squeezed so much information into the screen that it was hard to garner any useful information from it otherwise.

We weren’t convinced that the feedback was valuable. Accommodating these changes would have meant breaking existing patterns, which was something we didn’t want to do without being sure.

We also weren’t happy about making availability more prominent, as this would make the appointments visually weaker. That is, fixing this problem could inadvertently end up creating another, equally weighted problem. We wanted to let the content do the work instead.

The real problem, we thought, was asking users their opinion first, instead of giving them tasks to complete. People can be resistant to change, and the questions we asked were about their opinion, not about how to accomplish what they need to do. Ask anyone their opinion and they’ll have one. Like the Coca-Cola and Pepsi taste tests, what people feel and say in user research can be quite different than how they behave in real life.

So we tested the same design again. But this time, we started each session by asking users questions that the schedule page should be able to answer. For example, we asked “Can you tell me when you’re next available?” and “What appointment do you have at 4 p.m.?”

Users looked at the screen and answered each question instantly. Only afterward did we ask users how they felt about it. Naturally, they were happy—and they made no comments that would require major changes. Somewhat amusingly, this time one participant said they wanted their availability to be less prominent because they didn’t want their manager seeing they had free time.

If we hadn’t changed our approach to research, we might have spent a lot of time designing something new that would have had no value for users.

Canceling an appointment

The last feature involved giving users a way to cancel an appointment. As we were transitioning away from using BookingBug, there was one situation where an appointment could have been booked in both BookingBug and the application—the details of which don’t really matter. What is important is that we asked users to confirm they understood what they needed to do.

The confirm cancellation page.

The first research session had five participants. One of those participants read the prompt but missed the checkbox and proceeded to submit the form. At that point, the user was taken to the next screen.

We might have been tempted to explore ways to make the checkbox more prominent, which in theory would reduce the chance of users missing it. But then again, the checkbox pattern was used across the service and had gone through many rounds of usability and accessibility testing—we knew that the visual design of the checkbox wasn’t at fault.

The problem was that the prototype didn’t have form validation. In production, users would see an error message, which would stop them from proceeding. We could have spent time adding form validation, but there is a balancing act between the speed in which you want to create a throwaway prototype and having that prototype give you accurate and useful results.

Summary

Coca-Cola wanted its world-famous cola to test better than Pepsi. As soon as tests showed that people preferred its new formula, Coca-Cola ran with it. But like the design of the schedule page, it wasn’t the product that was wrong, it was the research.

Although we weren’t in danger of making the marketing misstep of the century, the design of our tests could have influenced our interpretation of the results in such a way that it would have created a lot more work for a negative return. That’s a lot of wasted time and a lot of wasted money.

Time with users is precious: we should put as much effort and thought into the way we run research sessions as we do with designing the experience. That way users get the best experience and we avoid doing unnecessary work.

Categories: thinktime

Samizdat is in the writing

Seth Godin - Thu 02nd Nov 2017 19:11
Under oppressive regimes, samizdat spreads. Forbidden dissident writing, informally published, hidden, spread from hand to hand. Reading it encourages and empowers other dissidents. But writing it--writing it is the true disruption. Because the act of saying it, saying it clearly,...        Seth Godin
Categories: thinktime

The work not yet done

Seth Godin - Wed 01st Nov 2017 18:11
Could be... That you don't know what needs to be done. That you don't know how to do what needs to be done. That you're afraid to do what needs to be done. It's frustrating. We want to move up,...        Seth Godin
Categories: thinktime

Web Typography: Designing Tables to be Read, Not Looked At

a list apart - Wed 01st Nov 2017 00:11

A note from the editors: We’re pleased to share an excerpt from Chapter 2 of Richard Rutter’s new book, Web Typography.

Good designers spend a great deal of time sweating over typography. They agonise over typefaces, iterate through type scales and meticulously apply white space, all in the service of the reader. Then comes along a table with the temptation to get creative, and all thoughts of the reader go out of the window. And yet tables are there to be read, referenced and used, not merely looked at.

Set tables as text to be read

Tables come in many forms. Some contain simple numbers, others are complex with mixtures of numeric data and textual information. Some require reading row by row, others are scanned vertically. The potential use for tables is as varied as the written word. They can be financial statements, bus timetables, multilanguage dictionaries, tables of contents, numerical conversions, pricing options, feature comparisons, technical specifications, and so on.

Despite the huge variation in table size, complexity, contents and purpose, every table shares two simple design principles: they should be readable and support a sense of the data held within. They should not be prettied up to satisfy a sense of aesthetic when simply looked at. That said, a well-designed table can still be a thing of beauty but with the form following the function. Tables are not pictures of data: they are catalogues of data to be perused, parsed, referenced and interrogated. A well-designed table will enable the information to be read and understood, and will reveal the patterns and correlations inherent in the data. As Jan Tschichold, the virtuoso of typography design, put it in Asymmetric Typography1:

Tabular matter need no longer be a rather unpleasant job to design: on the contrary, it can become a really charming and artistic exercise, in no way less interesting than any other area.

Wherever possible plan the readability of every table in advance. Your design process should be an investigation into making the data undemanding to read, simple to follow and easy to extract.

Just as you wouldn’t design body text with the aim of fitting as many words as possible on the screen, so you shouldn’t treat designing a table as an exercise in cramming as much data as possible into one space. You might be tempted to reduce the text size of your table – and if the data is entirely numeric you might be able to get away with it. Your reader should still be able to be comfortably read and interpret the table from their normal position, without needing to lean in.

Don’t stretch tables

Many designers will instinctively apply a width to their tables – just as they might an image – stretching them to fill the text column or page. And that is the appeal of setting tables full-width: you can make them look somewhat image-like when viewed from afar. However, while a table spread across the screen might look preferable from a distance, on closer inspection it will be harder to read as the data will be unnecessarily separated. To add insult to injury, tables set full-width are often replete with background colours and borders to give the table further the texture of an image, when what your reader really requires is the texture of text. For the sake of your readers, avoid these temptations.

You might consider making all the columns an even width. This too does nothing for the readability of the contents. Some table cells will be too wide, leaving the data lost and detached from its neighbours. Other table cells will be too narrow, cramping the data uncomfortably. Table columns should be sized according to the data they contain. Columns of small numbers should be narrow, and columns of paragraphs should be relatively wide. This sounds like a lot of effort, and for a print designer it would be, as they would have to size each column manually in their layout software. Fortunately, web browsers are very clever when it comes to laying out tables and will do all that hard work for you. Browsers have been laying out tables automatically according to complex algorithms since long before CSS came along – just let them do their thing.

Keep table furniture and fills to a minimum

The statistician and information designer Edward Tufte introduced the concept of data-ink in his 1983 classic, The Visual Display of Quantitative Information. He defines data-ink as ‘the non-erasable core of the graphic’, whereas non-data-ink is the ink used in the graphic, not to directly represent data but for scales, labels, fills and edges. Tufte goes on to define the data-ink ratio as the proportion of ink that is used to present actual data compared to the total amount of ink used in the entire graphic. The goal is to design a graphic with the highest possible data-ink ratio (tending towards 1.0) without eliminating what is necessary for effective communication.

Where Tufte talks about graphics he includes charts, diagrams and tables, and where he uses ‘ink’ we can think of pixels. In terms of tables, he’s saying that we should remove almost everything in the design which is not data or white space. Minimise furniture, maximise information. This is an ideal first principle to bear in mind when considering the typographic design of a table.

As a starting point, avoid any border or frame surrounding the table. This is a Victorian embellishment which is entirely unnecessary as text alignment will shape the table just fine.

Try to achieve a readable table using just alignment, spacing and grouping. Avoid zebra striping, tints and fills, and any other backgrounds. These can be superficially pretty but are usually a distraction. They serve to distort the meaning of the data by highlighting every other row to the detriment of neighbouring rows. Only use tints as a subtle means of guiding your reader’s eyes, and then only if you cannot arrange the data to that end. If you choose to tint, do so only in the primary direction of reading: down if lists, across otherwise.

When it comes to lines and borders between rows and columns – typographically referred to as rules – the same applies: use them judiciously and preferably not at all. In Asymmetric Typography Jan Tschichold sums this up wonderfully:

Tables should not be set to look like nets with every number enclosed. Try to do without rules altogether. They should be used only when they are absolutely necessary. Vertical rules are needed only when the space between columns is so narrow that mistakes will occur in reading without rules. Tables without vertical rules look better. Thin rules are better than thick ones.

Avoid using row or column borders unless the data alignment, spacing and grouping are not sufficient to guide your reader’s eye. If you do need to use rules for this purpose, use them in one direction only and employ a lighter colour to reduce the impact of the lines: you are making a distinction, not constructing a barricade.

Left-align text, right-align numbers, and align headings with data

In the spirit of treating tables as artefacts to be read, don’t centre text within tables. Align table text as you would anywhere else; that is, aligned left. As text in tables tends to end up in narrow columns, don’t justify the text either – leave it ragged-right – or you will end up with rivers flowing down the tables, potentially causing confusion and certainly harming readability. You can hyphenate, however, particularly if the table columns would otherwise have a pronounced rag.

Right-align numbers to help your reader make easier comparisons of magnitude when scanning down columns. To aid scanning in this manner you will need consistent precision of your numeric data; that is, use the same number of decimal places.

For consistency and ease of understanding, match the alignment of headings to the alignment of the data. Right-align headings of numeric data and left-align headings of columns with text, for example:

 

th.nums, td.nums { text-align: right; } Country Area Population GDP Capital Austria 83,858 8,169,929 339 Vienna Belgium 30,528 11,007,000 410 Brussels Denmark 43,094 5,564,219 271 Copenhagen France 547,030 66,104,000 2,181 Paris Germany 357,021 80,716,000 3,032 Berlin Greece 131,957 11,123,034 176 Athens Ireland 70,280 4,234,925 255 Dublin Italy 301,230 60,655,464 1,642 Rome Luxembourg 2,586 448,569 51 Luxembourg Netherlands 41,526 16,902,103 676 Amsterdam Portugal 91,568 10,409,995 179 Lisbon Spain 504,851 47,059,533 1,075 Madrid Sweden 449,964 9,090,113 447 Stockholm United Kingdom 244,820 65,110,000 2,727 London Align to the decimal point

You may find yourself not having control of numerical precision, or perhaps the data you’re working with is rounded to the same significant number rather than adhering to the same precision. In this case, simply right-aligning a column of numbers will not help your reader scan down the column – small, high-precision numbers will look at first glance like a large number. Instead, align numbers to the decimal point. This will enable your reader to more readily compare magnitudes among a wider variety of data:

+-------------+ | Call charge | +-------------+ | $1.30 | | $2.50 | | $10.80 | | $111.01 | | $85 | | N/A | | $.05 | | $.06 | +-------------+

Aligning to the decimal point was theoretically possible by using the HTML 4 char attribute on a <td> tag, but in reality it was never supported. The modern way to align numbers to a decimal point (or to any character, in fact) is through a new value of the text-align property, although at the time of writing this is languishing in the CSS Text Level 4 Module2 and support is patchy at best.

The syntax of the new value is simple. You include the alignment character (usually a full stop or comma) in quotes, followed by a space and your desired alignment keyword, which defaults to right if you omit it. For example, the following will centre the data and align to a decimal point as in our prior example:

td { text-align: "." center; }

By specifying different alignment characters you can lay out more complex tables in a useful way; in this example, aligning digits to ‘×’ and ‘:’.

Selected display standards Video standard Resolution Pixels Aspect QQVGA 160 × 120 19k 4 : 3 HQVGA 240 × 160 38k 3 : 2 QVGA 320 × 240 76k 4 : 3 WQVGA 480 × 272 130k 16 : 9 VGA 640 × 480 307k 4 : 3 SVGA 800 × 600 480k 4 : 3 XGA 1024 × 768 786k 4 : 3 HD 1260 × 768 967k 16 : 9 WXGA 1280 × 800 1,024k 16 : 10 SXGA 1280 × 1024 1,310k 5 : 4 UXGA 1600 × 1200 1,920k 4 : 3 FHD 1920 × 1080 2,073k 16 : 9 DCI 2K 2048 × 1080 2,211k 19 : 10 WQXGA 2560 × 1600 4,096k 16 : 10 4K UHD 3840 × 2160 8,294k 16 : 9 8K UHD 7680 × 4320 33,177k 16 : 9 Use tabular lining numerals in tables of numbers

Many tables, such as financial statements or timetables, are made up mostly of numbers. Generally speaking, their purpose is to provide the reader with numeric data, presented in either columns or rows, and sometimes in a matrix of the two. Your reader may use the table by scanning down the columns, either searching for a data point or by making comparisons between numbers. Your reader may also make sense of the data by simply glancing at the column or row. It is far easier to compare numbers if the ones, tens and hundreds are all lined up vertically; that is, all the digits should occupy exactly the same width.

Digits of the same width can inherently be found in monospaced fonts, and there is nothing wrong with choosing a suitable monospaced font to present a table of data (see ‘Combining typefaces’). However, many proportionally spaced fonts (those where a 1 is narrower than an 8, and a W is wider than an I) also come with additional sets of figures which are monospaced. These are called tabular numerals. As well as being of equal width, tabular numerals will be subtly designed differently from the standard proportional numerals. For example, a 1 will normally have a bar for its base, and a 0 (zero) may be designed slightly narrower to better fit the chosen number width. Tabular numerals are usually available in old-style and lining variations. Use tabular lining numerals to provide your reader with the most effective way to reference vertically and horizontally in tables of data.

Different numeral styles compared.

To specify tabular lining numerals, set the font-variant-numeric property with a value of lining-nums and tabular-nums:

table { font-variant-numeric: lining-nums tabular-nums; }

The equivalent properties for legacy browsers requiring font-feature-settings, use the lnum and tnum OpenType feature tags.

Proportional numerals

If you need to specify proportional numerals, set the font-variant-numeric property with a value of proportional-nums. For legacy browsers requiring font-feature-settings, use the pnum OpenType feature tag.

Put white space to work to group and separate

Having eliminated rules and fills (borders and backgrounds) from your table, you will need to apply white space to your table so your reader can make sense of it. It is at this point that you should remove from your mind’s eye all visions of spreadsheets and other such uniform grids, and think instead in terms of typography and simple gestalt grouping principles.

You will primarily need to separate the data so that each element can be individually identified and read as separate from the others. To have more control over the spacing, first collapse the spacing between borders:

table { border-collapse: collapse; }

In traditional HTML tables, adjacent cells each have their own distinct borders which are separated from each other, with the separation still present even if the borders are not. In the collapsed border model, adjacent table cells share borders. As we are removing (almost) all cell borders, and any we retain will be single key lines, the collapsed border model is the most appropriate.

Now apply padding to the table cells to separate the data. You’ll find that adding a smaller amount of padding to the top of the cell is a useful way to provide a visually balanced separation from the rows above and below. To ensure everything lines up nicely, apply the same padding to heading cells as to data cells. Because line lengths are often very short in tables, you can reduce the line height right down. In the following example, we’ve removed all additional line spacing, but you may need more depending on your choice of font and the amount of text in the table cells.

td, th { padding: 0.125em 0.5em 0.25em 0.5em; line-height: 1; }

The gestalt grouping principles most useful in tables are those of proximity and similarity. Move related data closer together to be distinct from other data; in other words, space apart groups of rows or columns. A by-product of grouping rows is that the data becomes much easier to scan and refer to than if the table consisted of a succession of undifferentiated rows. Ensure data of a similar content or meaning look similar at a glance, which you can do through alignment, colour and font style.

Table captions

We will attend to the typographic specifics of table captions in ‘Choosing typefaces for functional text’ but it’s worth noting now how to mark up captions for tables. If you are choosing to place your table inside a <figure> element, which is a perfectly reasonable thing to do, then use a <figcaption> element before or after the table. If your table is not inside a <figure> element, or you have multiple items in the figure, use the aptly named <caption> element, which HTML provides specifically for tables. Always write the <caption> tag immediately after the opening <table> tag and before any table data, like this:

<table> <caption> Imperial to metric conversion factors <p><i>Values are given to three significant figures</i></p> </caption> <thead> … </thead> <tbody> … </tbody> </table>

You can position the caption either above or below the table using the caption-side property and a corresponding value of either top or bottom.

caption { caption-side: bottom; }

The following table shows a caption and demonstrates gestalt grouping principles by separating the data into related rows:

Imperial to metric conversion factors

Values are given to three significant figures unless exact

To convert into multiply by Length inches millimetres (mm) 25.4 feet centimetres (cm) 30.48 yards metres (m) 0.91444 miles kilometres (km) 1.61 Area square inches sq. millimetres (mm²) 645 square feet square metres (m²) 0.0929 square yards square metres (m²) 0.836 acres hectares 2.47 Volume cubic inches millitres (ml) 16.4 cubic feet litres 28.3 imperial gallons litres 4.55 US barrels cubic metres (m³) 0.159

Note that, in this example, the numbers do not align to the decimal point. This is because the purpose of the table is for the reader to easily identify and extract a multiplication factor. In this instance there is no obvious use case for comparing the relative magnitudes of the factors, which is when decimal alignment would be useful.

Do not over-stylise tables

The French writer-aviator Antoine de Saint-Exupéry wrote3 perfection is attained not when there is nothing more to add, but when there is no longer anything to take away. Quoting de Saint-Exupéry may have become a cliché, but his idiom is entirely apt when applied to table design. There is no need to make a table look like a spreadsheet. A spreadsheet is a tool unto itself; a table is for presenting data and information that can be read. Spreadsheet software offers a multitude of options for table styles, which add text formatting, borders, background fills and all manner of ornament. They may make pretty pictures but do nothing for table readability, so do not try to emulate them. Tables can be beautiful but they are not works of art. Instead of painting and decorating them, design tables for your reader.

A typical spreadsheet-styled table set full-width with borders, fills and centred alignment. 1. Remove stretch and size columns to data. 2. Remove fills, gridlines, border and bolding. 3. Left-align text, right-align numbers and align headings with data. 4. Put white space to work to group and separate. 5. Use tabular lining numerals, consistent precision, and remove repetition. Adapt tables to small screens

Tables regularly require a fair bit of horizontal space to display the information they contain. Even when judiciously designed and edited, a typical table may need to be wider than the 45–75 characters we normally allow for paragraphs of text. For small screens, such as phones, designing readable tables which work under such cramped conditions presents us with a serious challenge. The best approaches always deal with each table on case-by-case basis, but that’s not always possible if we need to generically style whatever comes out of a CMS database.

One immediate approach is to use either a condensed font or a slightly smaller size (but not both smaller and condensed). In both cases, readability must remain paramount and other options should also be explored.

Consider setting oblique headings to save space

One way to save horizontal space, particularly when you have short pieces of data but long headings, is to set the headings at an oblique angle.

Using oblique headings to save space.

You can use a simple CSS translation to achieve the effect. You will also need to absolutely position the headings so the original width of the columns isn’t retained and they shrink to wrap the data instead.

th { transform-origin: bottom left; position: absolute; } th.degC { transform: translate(2.58em,-2em) rotate(-60deg); } th.degF { transform: translate(5.14em,-2em) rotate(-60deg); } Let the browser handle tables with horizontal scrolling

The simplest solution to help tables of any size and complexity is to let the browser lay out the table as best it can and render part of the table off-screen as necessary. Provided you then enable your reader to scroll the table sideways independently of the rest of the text, the table can be relatively easily brought into view.

Using a crawl bar to scroll a table into view.

To do this, first wrap your table in a <figure> element:

<figure class="fig-table"> <table> … </table> </figure>

Then apply the following simple rules to hide the portion of the table off-screen and enable your reader to scroll the table without affecting the rest of the text:

.fig-table { max-width: 100%; overflow-x: scroll; }

It is important not to set a width on your table; the browser can then compress the table as far as it can before overflowing off the screen. To preserve readability, make good use of non-breaking spaces and white-space:nowrap to limit the amount the data wraps in the cells. It’s better to have a readable table that requires scrolling than an unreadable one which doesn’t.

Linearise simple tables into lists

You can safely linearise simple data tables when space is limited. The tables most suitable for this treatment are lists of structured data; for example, an employee directory:

Name Email Title Phone Jones, Claire claire.jones​@domain.com Managing Director 01234 567890 Smith, Darren darren.smith​@domain.com Head of Sales 01234 567891

When there is not enough room for the table to render comfortably, we can set it with a completely different layout. This is less compact overall, and takes more space vertically, but it succeeds in fitting the table into a much narrower viewport:

Name: Jones, Claire Email: claire.jones@domain.com Title: Managing Director Phone: 01234 567890 Name: Smith, Darren Email: darren.smith@domain.com Title: Head of Sales Phone: 01234 567891

The two renderings of our employee directory table use exactly the same markup, comprising the conventional HTML elements you would expect in any table. The one addition is a data-title attribute on each cell enabling us to repeat the label in the list view, should we need to.

<th data-title="Name">Jones, Claire</th> <td data-title="Email">claire.jones@domain.com</td> <td data-title="Title">Managing Director</td> <td data-title="Phone">01234&nbsp;567890</td>

There are four simple steps to turning the table into a list, using a media query and CSS (no JavaScript is required).

  1. Identify the viewport width at which the table starts to render poorly.
  2. Apply display:block to all table-related elements so they align vertically instead of as a table.
  3. Hide the header row and any empty cells.
  4. Display labels for each data item (optional).

You will need to apply some additional styling for aesthetics and readability, but the responsiveness described can be accomplished in these few lines of CSS:

@media (max-width: 25em) { table, caption, tbody, tr, th, td { display: block; text-align: left; } thead, th:empty, td:empty { display: none; visibility: hidden; } th[data-title]:before, td[data-title]:before { content: attr(data-title) ": "; display: inline-block; width: 3.5em; } }

This technique was first popularised by Aaron Gustafson4.

Make tables responsive according to their purpose

There are many different techniques5 available for making data tables responsive. Some are simple CSS-only methods (we’ve covered two already); others are complex, enhanced by JavaScript. When considering which technique to use, ask yourself how your reader will use the table. In particular, consider if your reader is likely to compare either rows or columns – these kinds of tables need extra attention owing to the way they are used.

When being able to compare columns is important, one method is to hide non-essential fields and provide an option to turn them back on. This technique was popularised by Filament Group6 using a stocks table as an example:

A data-rich table as rendered on a large screen. The same table with hidden columns and options to toggle.

Tables are a frequently overlooked aspect of reading, sometimes overstyled, sometimes poorly thought out. Responsiveness is a particularly thorny issue as the best solutions depend very much on the utility of the table. Tables can be packed with data, rich in content and meaning. Give them the attention they deserve.

Want to read more?

This excerpt from Web Typography will help you get started. Order the full copy today.

Footnotes
  • 1. Asymmetric Typography by Jan Tschichold (1967, after 1935 original).
  • 2. Character-based Alignment in a Table Column (http://wbtyp.net/103) in the CSS Text Module Level 4.
  • 3. Terre des Hommes (translated into English as Wind, Sand and Stars) by Antoine de Saint-Exupéry (1939).
  • 4. ‘Responsive Tables’ (http://wbtyp.net/16) by Aaron Gustafson on Easy Designs blog (2013).
  • 5. See CSS-Tricks’ ‘Responsive Tables’ (http://wbtyp.net/148) for the latest options.
  • 6. Filament Group’s ‘Tablesaw’ (http://wbtyp.net/15) responsive table plug-ins.
Categories: thinktime

Machine unreadable

Seth Godin - Tue 31st Oct 2017 19:10
More and more, we create our work to be read by a machine. SEO specialists tell you how to write a blog post that Google will like. Your resumé needs to have the right keywords to get tagged. Everything has...        Seth Godin
Categories: thinktime

OpenSTEM: Election Activity Bundle

Planet Linux Australia - Tue 31st Oct 2017 15:10
For any Australian Curriculum HASS topic from Prep to at least Year 6, we can safely say “We have a resource on that!” So when, like here in Queensland, an election is suddenly called and teachers want to do some related activities in class, we actually already have the materials for you as these topics […]
Categories: thinktime

Russell Coker: Logic of Zombies

Planet Linux Australia - Tue 31st Oct 2017 01:10

Most zombie movies feature shuffling hordes which prefer to eat brains but also generally eat any human flesh available. Because in most movies (pretty much everything but the 28 Days Later series [1]) zombies move slowly they rely on flocking to be dangerous.

Generally the main way of killing zombies is severe head injury, so any time zombies succeed in their aim of eating brains they won’t get a new recruit for their horde. The TV series iZombie [2] has zombies that are mostly like normal humans as long as they get enough brains and are smart enough to plan to increase their horde. But most zombies don’t have much intelligence and show no signs of restraint so can’t plan to recruit new zombies. In 28 Days Later the zombies aren’t smart enough to avoid starving to death, in contrast to most zombie movies where the zombies aren’t smart enough to find food other than brains but seem to survive on magic.

For a human to become a member of a shuffling horde of zombies they need to be bitten but not killed. They then need to either decide to refrain from a method of suicide that precludes becoming a zombie (gunshot to the head or jumping off a building) or unable to go through with it. Most zombie movies (I think everything other than 28 Days Later) has the transition process taking some hours so there’s plenty of time for an infected person to kill themself or be killed by others. Then they need to avoid having other humans notice that they are infected and kill them before they turn into a zombie. This doesn’t seem likely to be a common occurrence. It doesn’t seem likely that shuffling zombies (as opposed to the zombies in 28 Days Later or iZombie) would be able to form a horde.

In the unlikely event that shuffling zombies managed to form a horde that police couldn’t deal with I expect that earth-moving machinery could deal with them quickly. The fact that people don’t improvise armoured vehicles capable of squashing zombies is almost as ridiculous as all the sci-fi movies that feature infantry.

It’s obvious that logic isn’t involved in the choice of shuffling zombies. It’s more of a choice of whether to have the jump-scare aspect of 18 Days Later, the human-drama aspect of zombies that pass for human in iZombie, or the terror of a slowly approaching horrible fate that you can’t escape in most zombie movies.

I wonder if any of the music streaming services have a horror-movie playlist that has screechy music to set your nerves on edge without the poor plot of a horror movie. Could listening to scary music in the dark become a thing?

Related posts:

  1. Logic and Pants I just read an interesting post about proposed new laws...
  2. Water Dogs – Good for Uplift? Update: I am now convinced that the Aquatic Ape theory...
Categories: thinktime

The thing about maps

Seth Godin - Mon 30th Oct 2017 19:10
Sometimes, when we're lost, we refuse a map, even when offered. Because the map reminds us that we made a mistake. That we were wrong. But without a map, we're not just wrong, but we're also still lost. A map...        Seth Godin
Categories: thinktime

Pages

Subscribe to kattekrab aggregator - thinktime