• User Authentication For Web And iOS Apps With AWS Cognito (Part 2)
    by David Tucker on September 21, 2017 at 12:50 pm

        In today's digital landscape, developers constantly need to be adding new tools to remain competitive and at the top of their craft. If you regularly create new web or mobile applications, then Amazon Cognito is a powerful tool that can cut 90% of the time it usually takes to set up a custom user-management solution. If that is intriguing to you, then let's continue the journey to learn more about what Amazon Cognito has to offer.The post User Authentication For Web And iOS Apps With AWS Cognito (Part 2) appeared first on Smashing Magazine. […]

  • How People Perceive Lossy Image Quality: A Study
    by by on September 21, 2017 at 12:30 pm

    The notion that lossy image quality is subjective is not an unreasonable hypothesis. There are many factors that play into how humans perceive quality: screen size, image scaling, and yes, even performance. Many research projects have tackled this subject, but I’ve recently launched a survey that attempts to understand how people perceive image quality in a slightly different way: in the context of performance. This image quality assessment serves up 25 different specimens, each of which is presented in a random lossy quality setting between 5 and 100, in both JPEG and WebP formats. As participants complete the survey, navigation, resource and paint timings are collected (when available) from the browser, as well as other client details such as a device’s resolution, pixel density, and many other pertinent details. The real work of gathering data begins. This is where you can help out. If you have five to ten minutes to spare, please head over to https://imagesurvey.site and participate. When the survey is finished, I’ll post the raw data and write and article (or two) on the findings. If further experimentation is required, that will be pursued as well. I don’t know what we’ll find out, but we’ll find out together with your input. So please participate! Thank you! Note: If you have feedback for how to improve the survey, feel free to comment! Just be aware that your feedback can’t be implemented in this run of the survey, but it could be useful in constructing any follow-up surveys. […]

  • Playing With Color: Vibrant Options For Apps And Websites
    by Nick Babich on September 20, 2017 at 12:16 pm

        Color is one of the most powerful tools in a designer’s toolkit. Color can draw attention, set a mood, and influence the user’s emotion, perception and actions. When it comes to the web and mobile app design, this is definitely a time of vibrant colors. Designers use vibrant colors to focus people’s attention on important elements and to make their designs memorable. In this article, I’ll summarize a few popular techniques of using vibrant colors in web and mobile design. Also, if you’d like to get started designing and prototyping your own web and mobile experiences, download Adobe XD.The post Playing With Color: Vibrant Options For Apps And Websites appeared first on Smashing Magazine. […]

  • The Ten Essentials for Good API Documentation
    by by on September 19, 2017 at 1:00 pm

    API documentation is the number one reference for anyone implementing your API, and it can profoundly influence the developer experience. Because it describes what services an application programming interface offers and how to use those services, your documentation will inevitably create an impression about your product—for better or for worse. In this two-part series I share what I’ve learned about API documentation. This part discusses the basics to help you create good API docs, while in part two, Ten Extras for Great API Documentation, I’ll show you additional ways to improve and fine-tune your documentation.  Know your audience Knowing who you address with your writing and how you can best support them will help you make decisions about the design, structure, and language of your docs. You will have to know who visits your API documentation and what they want to use it for.  Your API documentation will probably be visited and used by the following audiences.  Developers Based on their skills, experience, and role in projects, developers will generally be the largest and most diverse group. They’ll be using your docs in different ways. At Pronovix, we started conducting developer portal workshops with our clients to help them learn more about what developers need and how to best support their work—and what they’re really looking for in API documentation. This is also supported by solid research, such as the findings published in Stephanie Steinhardt’s article following a two-year research program at Merseburg University of Applied Sciences. Newcomers: Developers lacking previous experience with your API tend to need the most support. They will take advantage of quickstart guides that encourage them to start using your API—clear, concise, step-by-step tutorials for the most important topics, and sample code and examples to help them understand how to use it in real projects. If you can make onboarding pleasant for newcomers, they will be more likely to devote themselves to learning every nuance of your API. External developers: Developers already working with your API will come back repeatedly to your docs and use them as reference material. They will need quick information on all the functionality your API offers, structured in an easy to understand way to help them quickly find what they need. Debuggers: Developers using your API will encounter errors from time to time and use your documentation to analyze the responses and errors that crop up. Internal developers: API providers tend to focus so much on their external audience that they forget about their own developers; internal teams working on the API will use the API documentation, as well. These are just the most common use cases. Decision makers Decision makers like CTOs and product managers will also check out your API documentation and evaluate your API. They need to determine whether your API will be a good fit for their project or not, so it’s crucial to your business that this group can easily and quickly find what they’re looking for. Other audiences Although not as common, journalists, technical writers, support staff, developer evangelists, and even your competition might read your API documentation.  Remember the purpose of documentation The foundation of your API documentation is a clear explanation of every call and parameter. As a bare minimum, you should describe in detail: what each call in your API does each parameter and all of their possible values, including their types, formatting, rules, and whether or not they are required. Context-based structure People won’t read your API documentation in order, and you can’t predict which part they will land on. This means, you have to provide all the information they need in context. So following the best practices of topic-based authoring, you should include all necessary and related information in the explanation of each call. Context.IO, for example, did a great job documenting each of their API calls separately with detailed information on parameters and their possible values, along with useful tips and links to related topics. Examples In order to be able to implement your API, developers need to understand it along with the domain it refers to (e.g., ecommerce). Real world examples reduce the time they need to get familiar with your product, and provide domain knowledge at the same time. Add the following to the description of each call: an example of how the call is made an explanation of the request sample responses Studies have shown, that some developers immediately like to delve into coding, when getting to know a new API; they start working from an example. Analysis of eye-tracking records showed that visual elements, like example code, caught the attention of developers who were scanning the page, rather than reading it line by line.  Many looked at code samples before they started reading the descriptions. Using the right examples is a surefire way to improving your API docs. I’ll explore ways to turn good API docs into great ones using examples in my upcoming post “Ten Extras for Great API Documentation”. Error messages When something goes wrong during development, fixing the problem without detailed documentation can become a frustrating and time-consuming process. To make this process as smooth as possible, error messages should help developers understand: what the problem is; whether the error stems from their code or from the use of the API; and how to fix the problem. All possible errors—including edge cases—should be documented with error-codes or brief, human-readable information in error messages. Error messages should not only contain information related to that specific call, but also address universal topics like authentication or HTTP requests and other conditions not controlled by the API (like request timeout or unknown server error). This post from Box discusses best practices for server-side error handling and communication, such as returning an HTTP status code that closely matches the error condition, human-readable error messages, and machine-readable error codes. Quickstart guide Newcomers starting to implement your API face many obstacles: They are at the beginning of a steep learning curve They might not be familiar with the structure, domain, and ideas behind your API It’s difficult for them to figure out where to start. If you don’t make the learning process easier for them, they can feel overwhelmed and refrain from delving into your API.  Many developers learn best by doing, so a quickstart guide is a great option. The guide should be short and simple, aimed at newcomers, and list the minimum number of steps required to complete a meaningful task (e.g., downloading the SDK and saving one object to the platform). Quickstart guides usually have to include information about the domain and introduce domain-related expressions and methods in more detail. It’s safest to assume that the developer has never before heard of your service. Stripe’s and Braintree’s quickstart guides are great examples; both provide an overview of the most likely tasks you’ll want to perform with the API, as well as link you to the relevant information. They also contain links to contact someone if you need help. Tutorials Tutorials are step-by-step walkthroughs covering specific functionality developers can implement with your API, like SMS notifications, account verification, etc. Tutorials for APIs should follow the best practices for writing any kind of step-by-step help. Each step should contain all the information needed at that point—and nothing more. This way users can focus on the task at hand and won’t be overloaded with information they don’t need. The description of steps should be easy to follow and concise. Clarity and brevity support the learning process, and are a best practice for all kinds of documentation. Avoid jargon, if possible; users will be learning domain-related language and new technology, and jargon can instill confusion. Help them by making all descriptions as easy to understand as possible.  The walkthrough should be the smallest possible chunk that lets the user finish a task. If a process is too complex, think about breaking it down into smaller chunks. This makes sure that users can get the help they need without going through steps they’re not interested in. Twilio’s tutorials explain the most-likely use cases with sample apps in a wide variety of programming languages and frameworks.Universal topics To implement your API, there are some larger topics that developers will need to know about, for example: Authentication. Handled differently by each type of API, authentication (e.g., OAuth) is often a complicated and error-prone process. Explain how to get credentials, how they are passed on to the server, and show how API keys work with sample code. Error handling. For now, error handling hasn’t been standardized, so you should help developers understand how your API passes back error information, why an error occurs, and how to fix it. HTTP requests. You may have to document HTTP-related information as well, like content types, status codes, and caching. Dedicate a separate section to explaining these topics, and link to this section from each related API call. This way you can make sure that developers clearly see how your API handles these topics and how API calls change behavior based on them.  Layout and navigation Layout and navigation are essential to user experience, and although there is no universal solution for all API docs, there are some best practices that help users interact with the material. Dynamic layout Most good examples of API documentation use a dynamic layout as it makes navigation easier for users than static layouts when looking for specific topics in extensive documentation. Starting with a scalable dynamic layout will also make sure you can easily expand your docs, as needed. Single page design If your API documentation isn’t huge, go with a single page design that lets users see the overall structure at first sight. Introduce the details from there. Long, single page docs also make it possible for readers to use the browser’s search functionality. Stripe managed to present extensive documentation in an easy to navigate single page.Persistent navigation Keep navigation visible at all times. Users don’t want to scroll looking for a navigation bar that disappeared. Multi-column layout 2- or 3-column layouts have the navigation on the left and information and examples on the right. They make comprehension easier by showing endpoints and examples in context. Clearbit’s three-column layout displays persistent navigation (table of contents) on the left, references in the middle, and code examples on the right.Syntax highlighter Improving the readability of samples with syntax highlighting makes the code easier to understand. The syntax highlighter in action on Plaid’s API documentation site.If you’d like to start experimenting with a layout for your docs, you might want to check out some free and open source API documentation generators. To learn about the pros and cons of different approaches to organizing your API docs in the context of developer portals, this is an excellent article by Nordic APIs. Editing All writing that you publish should go through an editing process. This is common sense for articles and other publications, but it’s just as essential for technical documentation. The writers of your API docs should aim for clarity and brevity, confirm that all the necessary information is there, and that the structure is logical and topics aren’t diluted with unnecessary content.  Editors should proofread your documentation to catch grammar mistakes, errors, and any parts that might be hard to read or difficult to understand. They should also check the docs against your style guide for technical documentation and suggest changes, if needed. Once a section of documentation is ready to be published, it’s a good idea to show it to people in your target audience, especially any developers who haven’t worked on the documentation themselves. They can catch inconsistencies and provide insight into what’s missing. Although the editing process can feel like a burden when you have to focus on so many other aspects of your API, a couple of iterations can make a huge difference in the final copy and the impression you make. Keep it up-to-date If your API documentation is out of date, users will get frustrated by bumping into features that aren’t there anymore and new ones that lack documentation. This can quickly diminish the trust you established by putting so much work into your documentation in the first place. When maintaining your API docs, you should keep an eye on the following aspects: Deprecated features. Remove documentation for deprecated features and explain why they were deprecated. New features. Document new features before launch, and make sure there’s enough time planned for the new content to go through the editorial process. Feedback. Useful feedback you get from support, or analytics should be reflected in your docs. Chances are you can’t make your docs perfect at the first try, but based on what users are saying, you can improve them continuously. For all this to work, you will have to build a workflow for maintaining your documentation. Think about checkpoints and processes for the above mentioned aspects, editing, and publication. It also helps if you can set up a routine for reviewing your docs regularly (e.g. quarterly). Following these best practices, you can build a solid foundation for your API documentation that can be continuously improved upon as you gain more insight into how users interact with them. Stay tuned for part two, where I give you some tips on how to turn good API docs into amazing ones. […]

  • Building Inclusive Toggle Buttons
    by Heydon Pickering on September 19, 2017 at 11:26 am

        Some things are either on or off and, when those things aren’t on (or off), they are invariably off (or on). The concept is so rudimentary that I’ve only complicated it by trying to explain it, yet on/off switches (or toggle buttons) are not all alike. Although their purpose is simple, their applications and forms vary greatly. In this inaugural post, I’ll be exploring what it takes to make toggle buttons inclusive. As with any component, there’s no one way to go about this, especially when such controls are examined under different contexts. However, there’s certainly plenty to forget to do or to otherwise screw up, so let’s try to avoid any of that.The post Building Inclusive Toggle Buttons appeared first on Smashing Magazine. […]