http://galore.co.za/blog/feed/rdf/ http://galore.co.za/blog/feed/rss/ http://galore.co.za/blog/feed/ http://galore.co.za/blog/feed/atom/ http://galore.co.za/blog/comments/feed/
Print Shortlink

inspiration

OMG – UBUNTU

  • It’s Simple to Make Visual Studio Code Match Your Gtk Theme -

    Here's a useful Visual Studio Code extension that helps theme the app to match a slate of popular GTK themes, including Arc, Adapta and Ubuntu's Ambiance.

    This post, It’s Simple to Make Visual Studio Code Match Your Gtk Theme, was written by Joey Sneddon and first appeared on OMG! Ubuntu!.

  • How To Enable Fractional Scaling in GNOME 3.26 on Ubuntu 17.10 -

    Despite the best efforts of many fractional scaling wasn’t ready for the GNOME 3.26 release earlier this month. But those of you running GNOME on a HiDPI display need not despair as you can enable experimental fractional scaling in GNOME 3.26 — but only in the Wayland session. And this post, the one you’re reading, will […]

    This post, How To Enable Fractional Scaling in GNOME 3.26 on Ubuntu 17.10, was written by Joey Sneddon and first appeared on OMG! Ubuntu!.

  • Linux On Desktop

  • Cannonical to stop financial support to Kubuntu Developer after 12.04
  • Linux on Desktop : The Journey so far
  • All about Linux

  • Fedora 19 Released - Fedora project has officially announced the release of Fedora 19 code named Schrödinger's cat. Fedora 19 features the 3.9.0 kernel. For end users, the new features include the Cinnamon desktop environment, GNOME 3.8, KDE 4.10, and MATE 1.6 desktop; Out of the box support for extraction of RAR archives using File Roller archive utility, a new screen management software for KDE named KScreen, OpenVPN 2.3, and more.

    For the developers, most of the development tools like Python, Java, PHP, Ruby, GCC (4.8.x) - have been updated. But more importantly, Fedora 19 now includes the Node.js JavaScript runtime environment for developing fast, scalable network applications using the JavaScript programming language. MariaDB a fork of MySQL has also been included which replaces MySQL.

    How to download Fedora 19


    There are multiple desktops available for use with Fedora. Each has a slightly different look and feel and offers varying levels of customization. Visit fedoraproject.org/en/get-fedora-options and choose the one that strikes your fancy.

    If you are already using a previous version of Fedora, then it is possible to upgrade to Fedora 19. Visit fedoraproject.org/wiki/Upgrading to know more.

    You can find the full release notes here. Fedora also comes with comprehensive documentation on every aspect of the OS that the end user might encounter which is a big plus.

  • Making UEFI Secure Boot Work With Open Platforms - "UEFI Secure boot” is a technology that offers the prospect of a hardware-verified, malware-free operating system bootstrap process that can improve the security of many system deployments. Linux and other open operating systems will be able to take advantage of secure boot if it is implemented properly in the hardware. UEFI is meant to replace the Basic Input/Output System (BIOS) firmware interface present in all IBM PC compatible personal computers.

    Read more »
  • A List Apart

  • How People Perceive Lossy Image Quality: A Study -

    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.

  • The Ten Essentials for Good API Documentation -

    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.

    Screenshot of Twilio's tutorials page
    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.

    Screenshot of Stripe's API reference page
    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.

    Screenshot of Clearbit's API reference page
    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.

    Screenshot of Plaid's API documentation page
    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.

  • Ants Magazine

    Dev Web Pro

  • Microsoft Releases Third Party Add-ins to Outlook on Android -

    Microsoft just revved up its Outlook Android app making it more productive and fun for users. In a recent announcement, the tech giant announced that it has updated the software to now support a variety of third party add-in apps. Third party add-in apps became available to iOS users since [...]

    The post Microsoft Releases Third Party Add-ins to Outlook on Android appeared first on DevWebPro.

  • Amazon To Brace For Serious Contender Soon With Microsoft’s Acquisition of Cycle Computing -

    Among the top players in the tech industry, Amazon Web Services (AWS) is the undisputed king of cloud computing, leading the pack by a wide margin in the relatively new but lucrative segment. However, rivals do not plan to let AWS reign unchallenged. In fact, analysts believe that the Amazon [...]

    The post Amazon To Brace For Serious Contender Soon With Microsoft’s Acquisition of Cycle Computing appeared first on DevWebPro.

  • Six Revisions

    Useful Tools

    Papermashup

  • Awesome Material inspired audio player - I came across this nicely designed audio player on CodePen, put together by Michael Zhigulin It uses the waves.js click effect library inspired by Google’s Material Design. For this tutorial demo I’m using a royalty free track from bensound.com. What is Google Material? Google’s Material Design language has begun making its first appearances in the wild. Designers and technologists everywhere are aflutter with praise for the new design language, which aspires to unite Google’s expansive product line under a rich set of design styles and principles. Material is a culmination of design principles put together over many years of evolution. […]
  • Periscope style heart effect with CSS and JS - If you’ve seen the Periscope app heart animation, you’ll know what I’m talking about. It’s the one where you tap on the screen and a flurry of hearts appear and fade out animated up the screen. If you’re building a iOS native app you can check out this code, which uses the react native playground. The HTML This is our container that we’ll use to inject the hearts into. The CSS We use font awesome to produce the heart icons, set random colours on them and animate them using CSS. FlowOne and FlowThree control the animation of the hearts up […]