12 ms·
If I need graphic charts/diagrams, I've already passed the markdown stage. There's absolutely no workflow I can think of that is improved by my sitting there an
by arkades 7y ago
If I need graphic charts/diagrams, I've already passed the markdown stage. There's absolutely no workflow I can think of that is improved by my sitting there and trying to ASCII Art my way into a diagram. Does anyone go, hey, you know what would make my note-taking or web design faster and easier? Spending 20 minutes making an ascii art diagram instead of slapping the same three figures out in powerpoint in 20 seconds.
I love markdown. It's an elegant tool for many situations. My own workflow depends on using Kiwi and Noteplan on my phone with a common dropbox directory for their files, which is a project directory for Sublime on my notebook and desktop. All of my organization is a centralized set of markdown'd text documents, be it my calendar or my knowledge base, sync'd across all of my devices and super-easily edited, searched, or converted to web pages.
But there is a point where using a simple and elegant tool stops being simple and elegant - it can only be tortured so far outside its intended use-case before it stops being useful.
- guug 7y ago> If I need graphic charts/diagrams, I've already passed the markdown stage. I disagree. Linux kernel documentation and many manpages contain ascii diagrams that proved extremity useful for helping me understanding the them. I really hope to see diagrams adopted into the markdown standard (CommonMark).
- xamde 7y agoDiagrams with PlantUML in AsciiDoc are quite efficient. Faster than powerpoint.
- gregmac 7y agoI've included plantuml stuff in our internal documentation at work for a long time, and have got a lot of complements from people on how great our documentation is. I attribute a lot of this to the diagrams (mostly component and sequence diagrams), many of which are there just because of how simple and fast it is to create+maintain them with inline plantuml. Benefits: Fairly easy to learn syntax, and powerful enough for most technical documentation needs. Easy to edit, easy to consume. No launching some heavy desktop app, no worrying about keeping PNG+source files up to date. (I do often use liveuml.com for editing any non-trivial diagrams though.) Works with version control Consistent style even when different people are working on diagrams Drawbacks: Not that pretty. Someone even mildly proficient at PowerPoint can make better-looking diagrams (though it takes longer). If you're doing internal or technical docs this isn't worth it, but for marketing/end-user facing stuff, maybe. I'll often just give my plantuml diagram to marketing and let them have a graphic designer pretty it up. Less intuitive. The learning curve is a bit of a barrier for people that have spent years doing stuff in PowerPoint, and haven't yet bought into the other benefits. Especially for a simple diagram, it's hard to convince them to spend a couple hours so they can learn how to build it in 5-10 minutes with plantuml, vs just spending 10 minutes in PowerPoint. I think this is exacerbated by the fact a lot of the benefits come later when trying to edit and it gets more complex.
- yoz-y 7y agoPlantUML syntax is also a lot easier to maintain and update than an ascii chart which is basically a low res pixel art.
- svnpenn 7y agoHave you run into this? https://github.com/asciidoctor/asciidoctor/issues/1087 https://github.com/asciidoctor/asciidoctor/issues/1087 I love all the features of asciidoc but it bothers me they can't get the actual HTML generation right.
- arminiusreturns 7y agoAn alternative to both I like is the blockdiag programs, including seqdiag, netdiag, and rackdiag. Diagrams as text that can be properly automated.
- mzs 7y agoneat, thanks http://blockdiag.com/en/nwdiag/index.html http://blockdiag.com/en/nwdiag/index.html
- arminiusreturns 7y agoAn alternative to both I like is the blockdiag programs, including seqdiag, netdiag, and netdiag. Diagrams as text that can be properly automated.
- johnjungles 7y agoI agree, but maybe it’s syntax. MermaidJS has pretty quick and easy syntax that makes whipping up diagrams simple enough for me to convert.
- ggerganov 7y agoI actually like using ascii diagrams for relatively simple graphs, because I can incorporate them directly in my source code comments. Recently I even made a simple web page where you can create easily ascii diagrams using dot [0] [0] https://dot-to-ascii.ggerganov.com/ https://dot-to-ascii.ggerganov.com/
- mumblemumble 7y agoI'd be pretty happy with the ability to do inline graphviz diagrams. If I'm using Markdown then I'm not really after super great presentation quality, so not having a lot of control over layout doesn't necessarily bother me as long as I can describe the graph quickly.
- hamburglar 7y agoI think I kind of like how this thing lets you do either quick ASCII art diagrams or embed graphviz (via Gravizo). The syntax for inserting Gravizo diagrams isn't too bad: ![Figure [graph]: A more complex graph example](http://g.gravizo.com/svg? digraph G { main -> parse -> execute; main -> init; main -> cleanup; execute -> make_string; execute -> printf init -> make_string; main -> printf; execute -> compare; })
- throwGuardian 7y agoASCII diagrams aren't competing with powerpoint, diagrams made with sequence js, mermaid js, etc. are. For the particular offerings of these libraries, a higher quality, professional looking output is generated in a shorter time than powerpoint. And most importantly, one can version control it, as the source is plain text
- mankash666 7y agofully agree
- jimws 7y ago> But there is a point where using a simple and elegant tool stops being simple and elegant - it can only be tortured so far outside its intended use-case before it stops being useful. An alternative tool I've begun to like is TeXMe: https://github.com/susam/texme https://github.com/susam/texme. It is like Markdeep but minimal--does not support any fancy features. Just plain Markdown and Latex. Very useful for note taking in a file that can publish itself. I don't think I can draw fancy diagrams while taking notes live so I don't need diagrams. So this simple tool serves me well.
- JoshTriplett 7y agoTeX doesn't preclude diagrams. I use TikZ extensively, and I've found it much easier than any graphical diagram tool I've ever used. (As with most of TeX, it has a learning curve, but then a much easier steady-state after that learning curve.)
- timdorr 7y agoI kind of want the opposite of this: A GUI tool I can draw some diagram stuff out in that renders down to ASCII art. Bonus points if it renders to Markdeep (or an equivalent) to be re-rendered as SVGs or whatever later on. Edit: Here we go - http://asciiflow.com/ http://asciiflow.com/
- tiziano88 7y agohttp://asciiflow.com/ http://asciiflow.com/
- rozab 7y agoThis is cool, but could benefit from some figlet-like text options
- Razengan 7y agoThere's also https://monodraw.helftone.com https://monodraw.helftone.com that lets you draw directly in ASCII.
- munfred 7y agoWell actually that's more like Unicode Art ;)
- francislavoie 7y agoOf course it's Mac only. :(
- anigbrowl 7y agoI like it when these use actual box-drawing characters, ie https://en.wikipedia.org/wiki/Box-drawing_character https://en.wikipedia.org/wiki/Box-drawing_character or https://en.wikipedia.org/wiki/Code_page_437 https://en.wikipedia.org/wiki/Code_page_437. Boxes made out of asterisks, dashes, and slashes appeal to me about as much as cutlery made out of recycled tin cans and coat hangers; it's the worst of both worlds, too ugly to qualify as real graphics and too distracting to be useful as text. Weirdly, the look worse than 'graphics' on the Commodore PET or TRS-80 (whose 'graphic' characters were helpfully printed on the keys and accessible through combination button presses).
- sergiomattei 7y agoYeah, I thought the same when looking at this. Text editing my way to ASCII diagrams is time consuming and brings little value for my time.
- type0 7y agoThe worst part isn't that it's time consuming but simple changes often require you to redraw the whole thing again. So for the most part a simple mermaid or graphviz is much more appropriate.
- dnautics 7y ago> There's absolutely no workflow I can think of that is improved by my sitting there and trying to ASCII Art my way into a diagram. Does anyone go, hey, you know what would make my note-taking or web design faster and easier? Documentation embedded in code docstrings. Yes, I could link to an external SVG but if you did that it wouldn't look great if I have to query the documentation via REPL.
- kyllo 7y agoFor simple graph diagrams it's easy enough to open up a separate graphviz .dot file, write up a graph specification, run it through dot or neato, and include the .png in your markdown file. And then automate this with a Makefile.
- ti_ranger 7y ago> For simple graph diagrams it's easy enough to open up a separate graphviz .dot file, write up a graph specification, run it through dot or neato, and include the .png in your markdown file. And then automate this with a Makefile. Or just use zim ( https://zim-wiki.org/ https://zim-wiki.org/ ) which allows you to embed graphviz diagrams in any 'page', and many other features.
- UweSchmidt 7y agoSounds interesting, would you mind sharing your workflow and your makefile? I tried graphviz ages ago and think it's a powerful and underused tool.
- gregopet 7y agoAsciiDoctor has GraphViz (and PlantUML plus a few more) available inline (it handles the conversion for you). The syntax has a few differences to Markdown but it's not too hard to adapt plus it has a few other awesome features that I always miss when in Markdown.
- UweSchmidt 7y agothanks
- kyllo 7y agoSure! I use pandoc to render Markdown, but you can use whatever Markdown processor you like in place of pandoc. Makefile all: example.html example.html: example.md example.png pandoc $< -o $@ example.png: example.dot dot -Tpng $< -o $@ example.dot digraph G { foo -> bar; } example.md # Example 
- joshvm 7y agoThe main advantage I see is that the markdown diagram is understandable in plaintext. That's quite a powerful idea because you don't need to understand any intermediate language. Graphviz and mermaid are interpretable, but not in an immediately visual way. I would be interested in a solution that can take graphviz files and output markdown-friendly diagrams, which can then be compiled back into vector diagrams.
- samatman 7y agoPerl to the rescue! https://codeyarns.com/2017/10/21/how-to-convert-dot-graph-to-ascii/ https://codeyarns.com/2017/10/21/how-to-convert-dot-graph-to...
- joppy 7y agoWe could also use a higher-bandwidth format than plain text? There is a lot of technical content which could be improved greatly by easy graphical tools for diagrams, equations, and so on, which is going a bit by the wayside because of the all-in-on-plaintext attitude. I think there is a lot of opportunity for clearer communication being totally passed over because of our collective inertia with respect to making better tools which would allow this kind of thing.
- thu2111 7y agoThe usual difficulty with moving beyond plain text is diffing/patching. Text has battle tested and decent visualisations for viewing the delta between two versions. Other formats generally don't. How do you visualise the diff of a diagram? How do you integrate it with git? That seems hard.
- joppy 7y agoIt’s a fair point, but again I think that it’s a very small price to pay for the improved communication. Things do seem hard, but we solve very hard problems in programming all the time (or so it seems), except when it comes to our tools. Plain text is still king when it comes to code because it is so easy to diff (which I think is a good choice), but how about my silly comments explaining how a system works rather than just drawing it and embedding that in a comment? I think there is a lot of potential there.
- sipjca 7y agoYeah ASCII Art is not ideal for drawings like this. I get frustrated enough at work writing comments requiring drawings. I can’t imagine trying to do that here. Maybe something very simple: A->B<-C similar to the syntax described for causal diagrams in Judea Pearl’s “The Book of Why”
- inetknght 7y ago> Does anyone go, hey, you know what would make my note-taking or web design faster and easier? Spending 20 minutes making an ascii art diagram instead of slapping the same three figures out in powerpoint in 20 seconds. Yes, I do. I spend my time in a terminal all day and ASCII art is way more useful than an image reference which will never be able to load. Show me a tool to export that powerpoint to ASCII and I'll be happy.
- freddie_mercury 7y agoThere's no reason images can't be displayed in terminals other "that's not how terminals work" historical baggage. iTerm2, as one example, can display images just fine.
- inetknght 7y agoIf I wanted images in my text I would use Code. Images are fine as long as they don't fuck with line counts or column counts.
- mjfl 7y agoIn my opinion it's way better to have things all in one program. The clumsiness of needing to open up a heavyweight program like Powerpoint to then copy and paste the figure somehow into your document every time you revise is very annoying to me. Plus it's less portable.
- abraxas 7y agoThis is why Microsoft invented OLE many decades ago. Admittedly it was a clunky, heavy and proprietary solution just like most other tech out of that company.
- xtracto 7y agoXML (via svg) can potentially be great for that... it saves the "what" so we only need software that does something useful with it.
- littlestymaar 7y agoPlaintext gives you straightforward integration with git though, which is waaaay better than the built-in collaborative version control you have in MS Office.