Almost agree, big issue with diagrams is that some people don't care about them and others take them as The Truth given by God, which creates a bunch of problems, especially because diagrams need to be updated, and as most docs they often aren't. Diagrams stop being connected to things they describe and no one ever has time to update them or knows how to update them (because they don't know how new version should look like).
Well said. A diagram needs to be derived from the code it describes and change along with it without requiring a heavy process outside of regular development... which was pretty much the thesis we had when we started the open source AppMap project.
I love the idea of AppMap.. I have always struggled on writing the docs of my code as I am this kind of people who finds it difficult to explain something.. a visual presentation would help for sure 😇
I do agree, diagrams in documentation are often out of date, and I tend to not use them that much. Tools like mermaid make it easier to keep things in sync, but it's still work (as good documentation always is).
I probably draw 100 diagrams for designing and engineering for every diagram I put into documentation :]
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Almost agree, big issue with diagrams is that some people don't care about them and others take them as The Truth given by God, which creates a bunch of problems, especially because diagrams need to be updated, and as most docs they often aren't. Diagrams stop being connected to things they describe and no one ever has time to update them or knows how to update them (because they don't know how new version should look like).
Well said. A diagram needs to be derived from the code it describes and change along with it without requiring a heavy process outside of regular development... which was pretty much the thesis we had when we started the open source AppMap project.
I love the idea of AppMap.. I have always struggled on writing the docs of my code as I am this kind of people who finds it difficult to explain something.. a visual presentation would help for sure 😇
Good point!
I do agree, diagrams in documentation are often out of date, and I tend to not use them that much. Tools like mermaid make it easier to keep things in sync, but it's still work (as good documentation always is).
I probably draw 100 diagrams for designing and engineering for every diagram I put into documentation :]