4 ms·

I love asciiflow.com for creating these sort of pictures. I'm a firm believer that the closer your documentation is to your code the better maintained it will b

I love asciiflow.com for creating these sort of pictures. I'm a firm believer that the closer your documentation is to your code the better maintained it will be.

rocqua 4y ago
Could this kind of documentation be an exception? After all, it can be quite hard to edit these pictures.
- rkangel 4y ago
  I think you want to lean heavily into the words and use pictures sparingly where they really add value. They're also not completely uneditable - you can just dump them back in asciiflow and fiddle with them if you want to make a change. I also find that usually the pictures capture a fairly high level structural concept - the sort of thing that changes a bit less. Sometimes I do a message sequence chart and editing to add an extra message is usually pretty easy.
wernsey 4y ago
I really liked the simplicity of the older asciiflow. So much so that I keep a bookmark to the wayback machine for it [1] Not too long ago I had a project that was implemented as a complex state machine where the requirements kept changing, and keeping the documentation as an ASCII diagram in the source code had a couple of benefits: * It meant that the documentation could be updated when the code had to be changed * I didn't have to hunt for the diagrams on the project wiki when I made these changes. * The diagram was kept in version control with the rest of the code. Each commit/branch had a diagram that accurately reflected its state. I could then use Ditaa to convert the diagram to a more appropriate format when updating the project's wiki or emailing the customer [1] https://web.archive.org/web/20130813045206/http://www.asciiflow.com/#Draw https://web.archive.org/web/20130813045206/http://www.asciif... [2] https://github.com/stathissideris/ditaa https://github.com/stathissideris/ditaa

4 ms·

I love asciiflow.com for creating these sort of pictures. I'm a firm believer that the closer your documentation is to your code the better maintained it will b

by rkangel 4y ago

I love asciiflow.com for creating these sort of pictures. I'm a firm believer that the closer your documentation is to your code the better maintained it will be.

rocqua 4y ago
Could this kind of documentation be an exception? After all, it can be quite hard to edit these pictures.
- rkangel 4y ago
  I think you want to lean heavily into the words and use pictures sparingly where they really add value. They're also not completely uneditable - you can just dump them back in asciiflow and fiddle with them if you want to make a change. I also find that usually the pictures capture a fairly high level structural concept - the sort of thing that changes a bit less. Sometimes I do a message sequence chart and editing to add an extra message is usually pretty easy.
wernsey 4y ago
I really liked the simplicity of the older asciiflow. So much so that I keep a bookmark to the wayback machine for it [1] Not too long ago I had a project that was implemented as a complex state machine where the requirements kept changing, and keeping the documentation as an ASCII diagram in the source code had a couple of benefits: * It meant that the documentation could be updated when the code had to be changed * I didn't have to hunt for the diagrams on the project wiki when I made these changes. * The diagram was kept in version control with the rest of the code. Each commit/branch had a diagram that accurately reflected its state. I could then use Ditaa to convert the diagram to a more appropriate format when updating the project's wiki or emailing the customer [1] https://web.archive.org/web/20130813045206/http://www.asciiflow.com/#Draw https://web.archive.org/web/20130813045206/http://www.asciif... [2] https://github.com/stathissideris/ditaa https://github.com/stathissideris/ditaa