Professor Martin Paul Eve of Birkbeck College, University of London, has released, for free, the visualisation software that helped him compare the texts of the novel Cloud Atlas. It displays the differences as a Sankey diagram. It’s intended to be used for comparing contemporary fiction, but it may have uses for analysing other long documents.
Tom Johnson has written two interesting posts on his blog on the “Documentation as Code” concept:
Documentation as Code can be interpreted in a few ways. Tom describes it as being able to store the documentation with the code:
From a technical angle, Etter argues that one should embrace lightweight markup languages, use static site generators, and store content in version control repositories with engineering code.
An other interpretation associated with this is that documentation should be seen as a design problem; it should be seen as part of the product (and seen in a similar way to the software code), rather than an add-on. If the documentation is stored with the code, it can mean that the requirements for documentation can be more closely linked to the code. When a requirement for a new feature is raised, so can a requirement for the related documentation. It can also mean that content that’s embedded in the UI, presented as on-boarding screens or presented as online Help, can be considered as different potential solutions to each user need.
Documentation as Code is a topic we touch on in our advanced technical writing training course. It’s an approach that we may see growing in popularity.
Yesterday, I saw a presentation by Hazel Southwell on the EU’s General Data Protection Regulation (GDPR), which will be implemented on the 25th May 2018. The impact in its data privacy and protection rules seem likely to affect pretty much every website, with the threat of hefty fines for those that do not comply.
Organisations providing personalised Help content, by storing information in cookies or monitoring the behaviour of users living in the EU by tracking their digital activities, will need to comply with the GDPR regulations. In particular:
- Businesses will have to adopt governance and accountability standards and meet their data privacy obligations.
- Clear and affirmative consent to the processing of private data must be provided, and the relevant information must be laid out in simple terms.
- Organisations need to consider the risks of transferring data (such as the storing of cookies or IP addresses) to countries outside of the EU.
One solution is to require users to log in to see information. However, this may be an unpopular and impractical solution for many users.
Microsoft has published its REST API Design Guidelines to the API community.
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.”
Just a quick update on some recent training-related news.
We’ve scheduled some new classroom courses:
We’re also continuing to add more courses to WriteLessons – our bundle of elearning courses for technical communicators looking to expand their core skills. We’ve added courses called “Writing and designing embedded Help” and “Markdown”.
WriteLessons is a subscription service – a bit like Netflix. You pay for it for as long as you need it. You can stop when you want, and the subscription will finish at the end of that month. You have access to all of the courses, which you can take at your own pace.
We’re currently working on a module on post-writing and verification, which focuses on editing and proof reading, which will be added to WriteLessons. You might also see a course on Cascading Style Sheets in the upcoming months.
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.
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
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.
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.