Content and Presentation
👉 Writing Tip #1: Don't call it "simple"
Key points in this video
Content = what is in the docs. Does the docs give the user all key information about the API? Do the docs have all the information a user needs to be productive or resolve problems?
Presentation = how the content is communicated. Can the user find and understand it?
- Delivery format (such as web page, Markdown, PDF, video, or hard copy)
- Appearance (fonts, colours, layouts, UI elements)
- Writing style (tone, language, sentence/paragraph structure)
- Information architecture, navigation, and discoverability (how content is structured and how easy it is to move between locations or locate items)
Content and presentation go hand-in-hand. Decisions you ake in one affect the other.
The audience determines both content and presentation. Some example considerations and possible decisions:
What minimum domain knowledge does my audience have?
- Include an explanation of possibly ambiguous or unfamiliar domain terms or tools and product features
- Avoid explaining familiar terms or tools like API, REST, or cURL
What are they likely to be using my API for?
- Include guides for most likely use cases
- Arrange resources (such as guides, endpoints) by most likely
- Use layouts that help with easy discovery/comparison of use cases
Browse through the documentation sites listed below. Try to identify elements of the content and presentation and what you think they did right or wrong. You can share your thoughts in the course Discussion area.
- Brankas: https://docs.brank.as
- LinkedIn: https://docs.microsoft.com/en-us/linkedin
- Reddit: https://www.reddit.com/dev/api
Some questions you can ask:
- Do the docs include key info as well as supporting info?
- How is the content organised? Does it make sense from a user’s perspective?
- Does the documentation prioritize likely use cases?
- Does the UI make for easy navigation and comparison of use cases?
- Do they avoid explaining familiar terms and rather focus on unfamiliar ones?