Liz Write the Docs Feeback

[lizargall]

Is this a docs issue?

• My issue is about the documentation content or website

Type of issue

Other

Description

This issue will capture various notes and feedback about Docker API documentation from Write the Docs conference. Thanks Sarah for creating this fun project.

Location

https://docs.docker.com/reference/api/engine/version/v1.49

Suggestion

Docker Engine API (1.49) Page

https://docs.docker.com/reference/api/engine/version/v1.49/

• Left nav bar should show where it exists.
• Title should indicate it's the most recent version
• Top of the fold should include a brief, user oriented summary of what the the Engine API is (no presumed context)
• Top section could include a brief sentence or two about what has changed since the last version and link to the release notes
• It is a long page, suggest a table of contents at the top
• I'm curious about the order of information. It may suit your audience, but would it be helpful to think about how apply a diataxis framework could help consistently sequence information (should never be dogmatically followed).
• If error messages are at the top because things might break because of this release, it might be helpful to note this. Interrogate what should be in the release note/troubleshooting space.

[lizargall]

Reference documentation page

https://docs.docker.com/reference/

• Top of the fold should have user oriented language. Use this xxx to yyy.
• Does to top of the fold need a link to release log/version numbers, latest news etc?
• Use definitive articles in descriptions or do not.
  • Defines the contents
  • The main

[lizargall]

Localization resources

• General process https://learn.microsoft.com/en-us/globalization/localization/localization-overview

• List of specific country localization style guides https://learn.microsoft.com/en-us/globalization/reference/microsoft-style-guides

• China specific guide https://aka.ms/chinese-simplified-styleguide

[sarahsanders-docker]

Thank you @lizargall for the feedback and the localization resources! Enjoyed meeting you at WTD :) I will keep you updated as we make improvements

[lizargall]

You're very welcome, likewise and thanks!