We look at the pros and cons of using the DITA standard, and the alternatives.
Back in July, we looked at creating an API documentation portal using MadCap Flare (see also: Example of API documentation portal using MadCap Flare) .
We done some further testing. We’ve created two new examples for API documentation that had been generated with the Stripe API look and feel and imported into Flare:
- Example A – Replacing the standard left hand Table of Contents with Flare’s local TOC on the right hand side.
- Example B – Removing the standard left-hand Table of Contents, so the descriptions and code samples can use the full width of the topic.
To compare the two, here is the standard “Stripe API” left-hand Table of Contents when imported into Flare.
We’ve not made any changes to the default Heading styles from the source files. The stylesheets would needed to be modified to make them consistent with the styles used on the other HTML pages in the project.
Cherryleaf’s Ellis Pratt will be speaking at the Write2Users Conference 2017 , which is being held 1-3 November at Copenhagen Zoo.
“The mission is to give attendees new skills for their day-to-day work with technical documentation and translation. You will learn about process optimization, new methodologies and new technologies. All delivered by industry experts, in-house specialists and practitioners from Scandinavia and abroad.”
Ellis will be speaking on “Agile in an Authoring World”.
The technical communication Venn diagram laptop stickers we created have been very popular. We’ve ordered more of them, and we’ve created some new designs. The new stickers have quotations from some of the people we’ve interviewed on the Cherryleaf podcast.
The stickers should arrive by the end of the month. Like before, we’ll post them off to anyone based in Europe who wants them.
We explore these questions from listeners:
- What’s your opinion of Zendesk and Mindtouch? Someone in our company thinks it might be a good idea to explore the idea of moving our Help content – have you heard of anyone doing this and then using it in a way of single sourcing etc?
- Our boss wants us to consider the idea of merging our Help content and our “Knowledge base” which is like articles/support troubleshooting etc. Whether this is our content going into the knowledge base or vice versa, we’re not sure in terms of direction. Do you have any opinions on merging article-based content like this into a Help Authoring tool or Help content into a “normal” website like that?
Cherryleaf’s Ellis Pratt has been included in the list of the 25 most influential people in Content Experience.
“With well over 1,700 individual nominations and votes, we created two separate lists this year: the best-of-the-best who influence an industry (voted on by an elite judging panel), and our top strategists implementing Content Experience across the entire customer journey.
What do we mean by ‘Content Experience?’
This role is not defined or exclusively owned by Product, Marketing, Sales, Support, or Success. Content Experience often lives in different departments depending on organizational structure, or as an independent vertical that manages all content produced by relevant departments.
Content Experience is the evolution of content strategy blending with technical communication. It’s an understanding that your content provides self-service experiences not only for your customers, but for potential prospects researching and/or buying your product as well.”
Thanks to MindTouch and the panel of judges. Congratulations everyone else on this list.
Here is early access to the latest episode on the Cherryleaf Podcast – Interview with Anne Gentle, author of Docs Like Code and Product Manager at Cisco. It will be published on the podcast channel on Monday.
- What is docs as code?
- Why do it?
- When might this approach might be applicable?
- The limitations
- Docs like code in development sprints
- Is it only for developer docs?
- Do you you need to understand programming?
- Why did you self publish?
- The benefits of taking this approach
- The future developments
- Automating document builds
Links to topics mentioned:
http://codewerdz.org/ Repository analytics for code and docs
Solr (Search Engine)
Why we use a ‘docs as code’ approach for technical documentation Jen Lambourne, GDS, GOV.UK