The State of Docker Container Documentation

We need to confront container documentation as the crucial, non-trivial problem that it is.

TL;DR — As far as I can tell, there’s currently no way of providing documentation for specific containers that we could fairly call canonical, “best practice,” or even all that widely used. This blog post suggests some currently available (but sadly not-great) workarounds but also points to what I think could be a fundamentally better path.

…The result is that questions like these virtually never have readily available, no-Google-involved answers:

  • How do I run this thing? Should I run a specific executable?
  • What’s the “blessed” way to run it?
  • Which ports should I use?
  • How do I debug it or run its in-container test suites?

Sometimes the problem is that no one has provided answers to these questions anywhere. More often, in my experience, the answers are out there but suffer from a really fundamental discoverability gap.

Read more at Medium