5 tips for writing better API documentation

by Teknita Team | Jul 8, 2022 | Uncategorized

1. Strive for consistency

Consistency of terminology, style, and organization are hallmarks of all good communication. It should be a principal foundation of your entire API program and the documentation process. To establish proper consistency throughout your documentation, ensure that the writing style and approach are the same throughout your team of writers. 
Following industry standards for your documentation, such as OpenAPI, can also help new users orient themselves quickly to a familiar pattern and establish further standardization. Clear navigation options and a consistent style improve discoverability for both features and your docs. 

2. Use plain language and a friendly tone

When writing your docs, keep the language plain and approachable, recognizing that jargon, slang, inside jokes, complicated acronyms, and the like have no place in your documentation. 

When the subject is complex, that’s when you should make your writing even simpler. It’s important to note that some users may be coming to your product with relatively little formal education. Your writing must be accessible to the full spectrum of possible users, from self-taught developers, non-native English speakers, and developers fresh out of college to experienced pros with little time to get the job done. Make their lives easier by providing documentation that is easy to understand. 

Here are a few other things to look out for when striving for an inclusive tone and plain language in your documentation: 

• Be alert to discriminatory language. 
• Use clear variable names and function names in code samples.
• Never assume. 
• Use gender-neutral terms. 
• Add alternate text to images. 

3. Provide essential information for the non-technical 

Using easy-to-understand, real-world examples can help make technical information more easily understandable for non-technical readers. This is where “try it” or mocking capabilities can make your documentation more useful. They can even make your API more compelling to potential customers.

Just remember, the person consuming your documentation won’t necessarily come from a developer background. 

4. Take a design-first approach

At Stoplight, we take a design-first approach to all that we do. This means focusing on building APIs for the humans behind them and considering all stakeholders who may interact with, create, or consume the API. This same approach can be applied to designing your documentation. Your API documentation needs to meet users where they are and speak to their needs. It needs to be more than a list of endpoints and methods. When writing your docs, write for every use case. As you draft your docs, the traditional developer, the non-traditional developer, the business counterpart, possible partners, and the end consumer perspectives should all be kept in mind.

5. Get creative with multimedia

If you aim to make your docs more engaging and inclusive, always try to find ways to showcase hands-on guides to implementation. Get creative, highlight use cases from diverse companies and developers, and provide sample apps and technical manuals based on real-world scenarios. Take advantage of multimedia like videos, graphics, or gifs to make your docs more enticing and cater to those who may absorb information more easily in a format other than strictly text. 

Write how you would want someone to explain something to you, taking into account the variety of people and backgrounds that may come across your documentation. Empathy for the developer and user is the primary way to work towards a better end-to-end developer and user experience. 

You can read more about writing API documentation here.

Teknita has the expert resources to support all your technology initiatives.
We are always happy to hear from you.

Click here to connect with our experts!

“Data in space” overview

by Teknita Team | Jul 7, 2022 | Uncategorized

Data in space is a new Power BI Mobile feature that uses augmented reality technology to create spatial anchors in the real world and attach Power BI data to them, so that data can be connected to the physical environment it is relevant to. You can put real-time data at the fingertips of employees where they need it, enabling them to make better, faster, and more informed decisions.

Data in space is powered by an integration of the Azure Spatial Anchors service and the Power BI Mobile app. This integration makes it possible to map real-world spaces in three dimensions, to create fixed, persistent spatial anchors in those spaces, and to attach digital content (Power BI reports) to these anchors. It also allows the app on any other device to search a space and look for anchors created in that space.

Data in space is set up in an organization by administrators. As part of setup, administrators assign users in the organization to one of two Data in space roles: writer and viewer:
– Writers can pin reports to locations as well as edit and delete pins;
– Viewers can scan to find and access pinned reports in a space.

A data in space writer goes to the location where it would be useful to have reports available in context on location. They open the report they want to pin in their mobile app, apply filters and slicers to configure the view they want the report to open to, and then they scan the space with their mobile app’s camera in order to map the space and pin the report to the desired location. When they pin the report, a spatial anchor is created and saved so that the report can later be found by others. They can do this multiple times in the same space, pinning different reports, or even different views of the same report. Later, a data in space viewer who needs to access the report on location can enter the space and find and access the pinned reports just by scanning the space with their mobile app’s camera.

You can read more about Data in space here.

Teknita has the expert resources to support all your technology initiatives.
We are always happy to hear from you.

Click here to connect with our experts!

Introducing Viva Sales, a new seller experience application.

by Teknita Team | Jul 1, 2022 | Uncategorized

Microsoft is introducing Viva Sales, a new seller experience application that brings together any customer relationship management technology (CRM), Microsoft 365 and Teams to provide a more streamlined and AI-powered selling experience.

Viva Sales is a new modern way of selling. As a smart CRM companion, Viva Sales makes sellers’ lives easier while enriching their CRM. Think about all the customer and deal insights that are already in Outlook, Teams and Office applications like Word, Excel and PowerPoint, but never make it into the CRM system. These insights are hard to capture because the seller is tasked with entering data manually. By enhancing the CRM system with customer engagement data from Microsoft 365 and Teams along with the power of artificial intelligence (AI), Viva Sales empowers sellers to be more connected with their customers, resulting in more personalized customer engagements and closed deals faster. This happens through a simple customer tagging feature, which automates the data capture, saves the seller time, and provides their organization with a more complete picture of deal and customer status. With AI embedded throughout, Viva Sales is like a sales coach to move deals along with recommendations and reminders. This intelligence layer provides sellers the information they need to help them be more productive.

You can read more about the Viva Sales here.

You need more details?

For a complete list of new features and fixed issues, or to discuss any particular use case for your business applications, please contact us.