Learn More
Resend Email
41
eo2875
3y

I'll point names today

Boss: Quick! The Xero integration is not working anymore!
Xero Documentation: place your client secret in the HEADERS
Me: * places client secret in headers *
Xero API: Bad Request!
Me:
*re-reads documentation*
*creates new client secret*
*1 hour of trying*
Hmmmm
* places client secret in request body, not in headers *
Xero API: Ok!

UPDATE YOUR DOCUMENTATION
TELL US ABOUT IT IN THE CHANGELOGS

rant

request

secret

client

api

xero

header
Favorite
Ranter
Comments
  • 11
    3y
    Psst, they can’t, it’s a secret 🤫
  • 6
    3y
    Documentation is code wich is executed by humans.
    All the rules about maintainance and refactoring for the other code applies to documentation too.
  • 6
    3y
    This is one of the reasons why I always say that code should be the documentation. Or the docs must be directly derived from the code automatically.
    I’ve seen enough wrong or outdated docs to cause my trauma.
  • 3
    3y
    @Lensflare
    Handwritten documentation is mostly crap. But automatically generated docs are normally useless when the code did not contain the beef inside comments already.

    Automatically generated UML is just horrible most of the time.

    And documentation for external users and non-devs definitely has to be reduced and enriched in some way.

    Good documentation is as hard as other good code.
    Machines sadly can't do that yet.
  • 3
    3y
    @Oktokolo absolutely agree.
    Automatic generation is good for more abstract concepts like REST definitions.
    I’ve had a workflow where swagger was generated from C# asp.net web api code. It was amazing.

    However, generating docs for classes where they just collect the signatures of the methods is complete useless bullshit.
Related Rants
devRant © 2021 Hexical Labs LLC
Privacy Policy  |  Terms of Service
Add Comment