8
coditect
11d

Don’t write documentation for other people, write it for yourself! It may all seem obvious today, but six weeks from now you’re not going to remember what you were thinking or why you wrote the code the way you did.

Comments
  • 0
    Documentation is a crutch.

    Most often there are better solutions. Either found via refactoring or/and by having infrastructure as code.

    Every piece of documentation is a failure in finding a clearer way.

    Exceptions exist. Public facing api should have openapi documentation and public libraries should have docstrings.
  • 0
    @TheCommoner282 when I hear this I feel most people are coming from a specific domain instead of looking at it outside of that specific domain.

    For instance needing to document your basic code functions just to explain them might be a problem in your actual code clarity.

    However, let's say that you're dealing with more SRE/DevOps style work, then having a good handbook with documentation can help fill in the gaps when touching multiple systems that haven't yet been fully automated or coded.

    I totally agree that much documentation is just noise to maintain. I do think that documentation that enables someone to better contribute that comes after you, or to understand a more complex system or process can be invaluable.

    My 10¢
Add Comment