5 ms·

Nice write-up. However, I would strongly recommend to replace your text-based diagrams, which are difficult to read, with ones produced by relevant tools (e.g.,

by ablekh 7y ago

Nice write-up. However, I would strongly recommend to replace your text-based diagrams, which are difficult to read, with ones produced by relevant tools (e.g., draw.io or a wonderful Mermaid project: http://mermaid-js.github.io/mermaid http://mermaid-js.github.io/mermaid).

aprdm 7y ago
I prefer text diagrams to all that you have linked. I don't understand how it is harder to read? Plus the text diagram stays in git with version control and diffs..
- ablekh 7y ago
  Well, it seems that our opinions on legibility of visual artifacts differ. It is harder to read, a) because of coarseness of diagrams' elements and b) because of additional mental effort needed to comprehend such an artifact as a whole. This is, of course, somewhat subjective, but I hope that I'm not alone in my qualitative assessment. As for having diagrams in version control, 1) my suggested approaches also allow for that and 2) I think that diffs for text-based diagrams would pretty much not be readable and, thus, of little value.
tsukurimashou 7y ago
> I would strongly recommend to replace your text-based diagrams, which are difficult to read, plain text is hard to read? I've heard it all
- dragonwriter 7y ago
  Text is easy to read as plain text. Diagrams not so much.
  - ablekh 7y ago
    Exactly. I'm pleased to finally hear from someone with a similar UX taste. :-)
hamburglar 7y ago
Couldn't disagree more. For simple boxes-and-arrows pictures like these, text-based diagrams are vastly superior to inlining an image. It's really nice when you can type "less readme.md" in a shell and actually get something useful. Markdown was designed to be human-readable as plain text too.
- ablekh 7y ago
  I partially agree. However, the key word in your comment is "simple". While, obviously, it is subjective, in my opinion, presented diagrams are hardly very simple (though, they are not that complex either). Yes, they are readable, but only after spending some mental effort that could be directed to better causes. Perhaps, a use of Unicode-defined pseudographics would improve the readability.
fpereiro 7y ago
Thank you for your suggestion! However, I'm a sucker for text diagrams (ever since I saw them in Jonesforth: https://github.com/nornagon/jonesforth/blob/master/jonesforth.S#L199 https://github.com/nornagon/jonesforth/blob/master/jonesfort...), so I strongly prefer to leave them as they stand. Hopefully they're still clear enough and get the point across.
- ablekh 7y ago
  You are welcome! As the author, of course, you are free to do whatever you want with your content. I was just sharing my friendly suggestion, based on my experience and UX taste ... :-)
- swah 7y ago
  I was finding your code [1] very compact, reminded me of Forth or those old array languages. This comment kinda explains it :) [1] https://github.com/altocodenl/acpic/blob/master/server.js https://github.com/altocodenl/acpic/blob/master/server.js

by ablekh 7y ago

aprdm 7y ago

I prefer text diagrams to all that you have linked. I don't understand how it is harder to read? Plus the text diagram stays in git with version control and diffs..

ablekh 7y ago
Well, it seems that our opinions on legibility of visual artifacts differ. It is harder to read, a) because of coarseness of diagrams' elements and b) because of additional mental effort needed to comprehend such an artifact as a whole. This is, of course, somewhat subjective, but I hope that I'm not alone in my qualitative assessment. As for having diagrams in version control, 1) my suggested approaches also allow for that and 2) I think that diffs for text-based diagrams would pretty much not be readable and, thus, of little value.

tsukurimashou 7y ago

> I would strongly recommend to replace your text-based diagrams, which are difficult to read, plain text is hard to read? I've heard it all

dragonwriter 7y ago
Text is easy to read as plain text. Diagrams not so much.
- ablekh 7y ago
  Exactly. I'm pleased to finally hear from someone with a similar UX taste. :-)

hamburglar 7y ago

Couldn't disagree more. For simple boxes-and-arrows pictures like these, text-based diagrams are vastly superior to inlining an image. It's really nice when you can type "less readme.md" in a shell and actually get something useful. Markdown was designed to be human-readable as plain text too.

ablekh 7y ago
I partially agree. However, the key word in your comment is "simple". While, obviously, it is subjective, in my opinion, presented diagrams are hardly very simple (though, they are not that complex either). Yes, they are readable, but only after spending some mental effort that could be directed to better causes. Perhaps, a use of Unicode-defined pseudographics would improve the readability.

fpereiro 7y ago

Thank you for your suggestion! However, I'm a sucker for text diagrams (ever since I saw them in Jonesforth: https://github.com/nornagon/jonesforth/blob/master/jonesforth.S#L199 https://github.com/nornagon/jonesforth/blob/master/jonesfort...), so I strongly prefer to leave them as they stand. Hopefully they're still clear enough and get the point across.

ablekh 7y ago
You are welcome! As the author, of course, you are free to do whatever you want with your content. I was just sharing my friendly suggestion, based on my experience and UX taste ... :-)
swah 7y ago
I was finding your code [1] very compact, reminded me of Forth or those old array languages. This comment kinda explains it :) [1] https://github.com/altocodenl/acpic/blob/master/server.js https://github.com/altocodenl/acpic/blob/master/server.js