Good morning/afternoon/evening,
I’ve been in IT over 25+ years and have seen technologies come and go. I say this not to be boastful but simply out of hope my words carry some weight based on experience.
I have dabbled in opensource for maybe 10 - 15 years for sure. And there are certain traits of a project that can make or break it’s success. One big deal breaker is documentation!
Here are some reasons:
- Written with an expectation the user knows what’s in your head.
- Written out of an arrogance in one’s own self.
- Written out of unwanted duty or disdain.
- Written with little knowledge of product.
- Written with too much knowledge of product and then some.
My experience has taught me good documentation or even great documentation is written when you consider the reader to be at a layman’s level. I know some of you will think that is ridiculous. But, let me ask you one question. What’s more important, to constantly deal with your reader’s interruptions seeking clarity of a poorly written document or a well vetted/understandable document written to inform it’s readers with all they need to know? In tech we’re all cramped for time and managing multiple projects that almost never go away. I promise you the only way to get control is to knock out issues/problem right the first time.
That said, the documentation for “Traefik” not terribly horrible, but lacking clarity of how it all fits together. Can we work on this?