Akshay Bhalotia - unREST among the docs

Akshay Bhalotia

DevX at Phyllo

Akshay's presentation

Akshay's slides

Q&A

• How do you present information that doesn't have a standardized documentation structure yet?
• How do you follow up? What do you measure? How do you get feedback that you are on the right track?
• How does the “Show, don’t tell” approach play together with accessibility rules and regulations of the law?
• What are the things that you don’t find solvable yet, but that you’d love to see implemented?

In the case of web APIs, a plethora of frameworks and tools are available that can help you write, test, and render the API specifications. But how can you build documentation around non-REST APIs? How to structure such content? How to design it in a better way? Technical writers face such problems and dilemmas daily, but designers and developers are also involved in the issue.

Creating useful documentation is hard, because it should provide all the necessary information, and it also has to be:

• easy-to-read,
• findable,
• helpful,
• concise, and
• prepared for returning users.

Creating useful documentation for Frontend SDKs or UI features is even harder. Especially, if you have to offer version-controlled and searchable docs for multiple such SDKs, based on different frameworks, under rapid, uncoordinated development with enhancements and breaking changes.

How to tackle the challenges

Information architecture and good writing are equally important.

• Create an intro page that can help users navigate to the section they are interested in the most.
• Don’t make your readers choose or guess where to start or what to do next. Use clear design.
• A table of contents at the beginning of the sections can help the returning users continue their journey seamlessly.
• Create a consistent documentation structure and page layout even if you have to document different platforms or frameworks: lower the context-switching cost for your readers.
  • Clearly explain everything, and highlight the possible differences.
  • Try to keep using the same flow and explanation steps or as similar as possible.
• Always provide the necessary context. Complete information helps developers make better decisions.
• Provide contextual environment- and platform-specific information as well.
• Keep all relevant information in the same place.
• Publish the reference pages separately.
• Write proper references for all parameters.
• Use a left- and right-side navigation where users can easily find all relevant options on the site and within the page.
• Clearly differentiate all available options, and provide suitable code samples.
• Use callouts, color notifications to draw attention to important points.
• Write a glossary.
• Publish a changelog.

Show, don’t tell. Design for developers!

What you can certainly do

• Think of the user.
• Think about what matters to them.
• Try not to overwhelm them, but keep all necessary information accessible.
• Help them understand interoperability between frameworks.