Microsoft publishes its REST API Design Guidelines

Microsoft has published  its REST API Design Guidelines to the API community.

Microsoft API guidelines sample

According to Gareth Jones, Principal API Architect, who announced its release:

“The effort got started from hearing two key points of feedback from customers:

It should be easier to get started with Microsoft APIs – Developers wanted to be able to run the curl tool against an API endpoint and get a human-readable result in just a few minutes

APIs for Microsoft cloud services should be consistent – Developers didn’t care that an API to work with an Azure virtual machine and an API to work with a user’s Office 365 documents were developed by different parts of the company, they were both from Microsoft and developers expected consistency

One of the goals of the effort was to find the right balance of detail in the guidelines. We wanted a document that sufficiently codified best practices, but was also approachable for individual contributor engineers and technical product/program managers.”

Microsoft is a member Open API Initiative, which has been spun out of Swagger.

According to Gareth Jones:

“These guidelines represent a multi-year, cross-company, collaborative process aggregating the collective experience of hundreds of engineers designing, operating, and running global scale cloud services from across Microsoft; and listening to feedback on our APIs from customers and partners.  We have attempted to incorporate those learnings along with industry best practices in the API space to create guidelines that API teams across Microsoft use on a daily basis.”

“It’s our hope that by contributing ours to the community conversation, we can add to the body of community knowledge and reusable content so that anyone can draw upon more collective knowledge when looking to set standards and guidelines within their organization.”

Links:

Policies and procedures writing course – 11th October

We’ve scheduled another of our policies and procedures writing course. It will be held on 11th October, in central London (WC2). 25% of the available places have been snapped up already, so book early!

Cherryleaf’s policies and procedures course teaches your staff how to write clear and effective policies and procedures, in a straightforward and efficient way. It is popular with staff from charities and the NHS, although it will benefit many writers of policies and procedures.

New Technical Author Lead vacancies in Cambridge

A client is looking to recruit two new staff:

“You’ll be working as part of a team that mentors and coaches the developers and user experience specialists to improve their technical writing skills by providing style guidance and feedback. This role requires you to be the proactive subject matter expert for user interface writing and technical documentation, and to be able to introduce new ideas and practices to the company.”

See: #4174 Technical Author Lead, Cambridge, £40-£60K DOE

Cherryleaf launches WriteLessons

WriteLessons, from Cherryleaf, provides you with access to a range of courses in technical communication. You have access to all of the courses contained within WriteLessons, which you can take at your own pace.

writelessons screenshot

Currently in beta, we’ll be adding extra courses over time. At launch, it contains:

  • DITA fundamentals
  • Single sourcing and content reuse training course
  • Introduction to content strategy
  • Documenting REST APIs
  • Managing technical documentation projects

You have access to all of the courses in the collection under a Netflix-style subscription plan.

See: WriteLessons

We live in interesting times

Although our blog is primarily about technical communication, Brexit is such a seismic event that it’s likely to affect technical writing companies and Technical Authors, amongst others, in the upcoming months and years. From a trading perspective, 2016 has, so far, been a very good year for us. However, we are allocating some time to prepare for whatever Brexit might throw at us in future years.

We’ve now identified two countries in the EU where we can establish a second sister company in short order, and various staff members are looking into obtaining a second passport (British, Irish or Spanish, depending on their personal circumstances). Depending on what the lawyers advise, it is likely the sister company would have the same shareholders and directors, but be a separate legal entity. In many ways, Cherryleaf could have its base anywhere in Europe. However, the UK is home, and we hope it can remain that.

Minimising the impact of Brexit on our clients in mainland Europe

We’d like to reassure Cherryleaf’s customers in mainland Europe and Ireland that we aim to minimise the impact on them as a result of UK’s decision to leave to the EU. The UK will remain in the EU for at least two years, and there should be little effect if the UK is able to negotiate access to the EU’s single market.

We are also looking at establishing a second company in either Ireland or a country in mainland Europe, so that we retain our legal and operating presence within the EU, should that not be the case.

Awards

The Spring 2015 edition of Communicator magazine and its special supplement on the Value of Technical Communication was entered in both the IoIC (Institute of Internal Communications) Awards in 2015 and the APEX Awards in 2016. One of Ellis’ articles (“Creating videos: tips and tricks”) was part of that issue.

We’ve just learnt this issue has won an APEX Grand Award. This is the first time Communicator has won a Grand Award. It has also won an IoIC Award of Excellence in 2015.

IOIC logo ISTC Spring 2015APEX Awards 2016

From http://apexawards.com/apex2016grandawardcomments.htm:

“This clean, appealing layout offers attractive spreads, a crisp, legible type schedule, with effective use of callouts, sidebars and captions. Content is equally exceptional, with fully vetted, well written articles on a wide range of professional topics. And the supplement on the value of technical communication is an effective ‘selling tool’ for managements and other key audiences. This magazine is precisely the kind of first rate publication you’d expect from a professional association of scientific and technical communicators.”

XML isn’t the only way to semantic content

I’ve been on the road speaking at a conference this week, and I’ve been listening to a lot of presentations on technical communication. Many of these were on the importance of having structured, semantic content when you are dealing with large amounts of content that needs to be translated into different languages and published in many different ways. All of these presentations put forward XML-based systems as the solution.

However, XML isn’t the only method for having semantic content. For example, AsciiDoc supports attributes, which can be used to add a semantic descriptions to headings, paragraphs and whole documents. You can use conditions in RoboHelp and Flare to categorise content. You can also store content in a database.

It’s sometimes useful to remember that XML isn’t the only way to semantic content.