Webpack.js.org: Dev - Allow Illustrations Via Mermaid
Webpack documentation can get a little text heavy at times. As discussed in several other threads (eg. #349), adding illustrations and screenshots would help add visual relief.
Starting with the concepts site section, we can identify critical topics that would benefit from visualisations, and I could help make them. After we identify such topics, I will post the graphic as a issue / PR which we can then discuss. I can make the final edits accordingly.
As a proof of concept, I made the following graphic for the "Entry" section in concepts.
I've kept the style very casual and informal, which should help with webpack's image of being "tough" and "not beginner friendly".
I'd love to hear which sections we should concentrate on, and if someone has a neat idea for a graphic, feel free to post, even if its a screenshot of a hand-drawn pencil sketch. It's going to prove to be very helpful.
Update
It seems we've all agreed on mermaid and we already have a few charts started stemming from various issues. Here's what it sounds like is needed to push it this forward:
- [ ] Figure out how to integrate Mermaid in our build/mardown-processing system.
- [ ] Finalize styling (hopefully we can get close to @pastelsky's design above).
- [ ] Include @rouzbeh84's webpack graph somewhere.
- [ ] Include this decision tree either in the shimming guide or a concepts page.
- Potentially create a flow chart like the one in #169 somewhere in the API section.
pastelsky
All 23 comments
I love this! I think that the concepts documentation would benefit most
from these. Also this would be great to explain webpack internals, the
compiler, compilation, resolver life cycles.
On Sun, Dec 4, 2016 at 6:31 PM Shubham Kanodia notifications@github.com
wrote:
Webpack documentation can get a little text heavy at times. As discussed
in several other issue threads, adding illustrations and screenshots would
help add visual relief.Starting with the concepts site section, we can identify critical topics
that would benefit from visualisations, and I could help make them. After
we identify such topics, I will post the graphic as a issue / PR which we
can then discuss. I can make the final edits accordingly.As a proof of concept, I made the following graphic for the "Entry"
section in concepts.[image: entry-graph copy]
https://cloud.githubusercontent.com/assets/8946207/20866237/47f1121e-ba4e-11e6-83b8-f4d14b3a0d79.pngI've kept the style very casual and informal, which should help with
webpack's image of being "tough" and "not beginner friendly".I'd love to hear which sections we should concentrate on, and if someone
has a neat idea for a graphic, feel free to post, even if its a screenshot
of a hand-drawn pencil sketch. It's going to prove to be very helpful.—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
https://github.com/webpack/webpack.js.org/issues/469, or mute the thread
https://github.com/notifications/unsubscribe-auth/AAZd9H4lwS7RI6_OaCMgnVXBoimWM2wJks5rErnEgaJpZM4LDlCh
.
pksjce
on 4 Dec 2016
Thanks @pksjce. Though including inline images in the current markdown setup wouldn't be a straightforward task. We'll probably have to host these images on webpack.js.org's server before we can link them in the markdown.
pastelsky
on 4 Dec 2016
@bebraw @skipjack @SpaceK33z what do you guys think? should I go forward with this?
pastelsky
on 10 Dec 2016
@pastelsky Yeah, sure. Would it be possible for you to share the style (push to webpack/media) so it's easier to keep it consistent across the documentation? #473 is related to this.
I wonder if it would be possible to create a nice style for graphviz. That would allow even coders to generate nice graphics.
bebraw
on 10 Dec 2016
@bebraw Sure. I can share the textures, fonts and shapes used. Although the graphic will still have to be created manually in a vector editor like sketch. I do not know much about graphviz.
pastelsky
on 10 Dec 2016
@pastelsky Essentially graphviz is based on a text based tree definition. It renders the images for you. Taken far enough it would be possible to make it so that you can write the definitions within Markdown and the system will render them as images while applying the project specific style.
The big advantage of going through a definition based approach like this is that then it's easier to get something consistent looking. You lose some power since it does the layout for you.
bebraw
on 11 Dec 2016
@pastelsky looks great, yea I definitely think we should go forward with this. I agree with @bebraw that enforcing a consistent style would be best (whatever method we choose for that). This is something @jhnns and I discussed a while back in regards to displaying modules in graphs/illustrations. He might be a good person to discuss this with as well -- any thoughts @jhnns?
skipjack
on 14 Dec 2016
My thoughts on the graphic style is that it would not work well as SVG, due to the grungy smudges. Where possible all logos and diagrams should be SVG. I suggest changing the watercolor fills to a flat color, the borders should be ok as outlines.
jaydenseric
on 12 Jan 2017
You're right. It's not just the background, but the casual look of the
strokes and fonts that'll make the svg version a bit heavy.
But then png's can look reasonably sharp on retina devices as well. And
png's are easier to share / reference / save. So it's a trade-off here.
The grunge fill was inspired in part by the graphic style on yarnpkg.org.
On 12 Jan 2017 6:18 a.m., "Jayden Seric" notifications@github.com wrote:
My thoughts on the graphic style is that it would not work well as SVG,
due to the grungy smudges. Where possible all logos and diagrams should be
SVG. I suggest changing the watercolor fills to a flat color, the borders
should be ok as outlines.—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/webpack/webpack.js.org/issues/469#issuecomment-272043090,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AIiCH7ggzSdrT_nmNMrpuUU5oeG3AwQ9ks5rRXhbgaJpZM4LDlCh
.
pastelsky
on 12 Jan 2017
@pastelsky Another option, https://github.com/knsv/mermaid . We could integrate that to markdown quite easily.
bebraw
on 19 Jan 2017
mermaid is pretty cool! got it started here mermaidGraph but it could definitely use some styling love haha.
i can get back at it tomorrow a bit though. Would love to look into it a bit further as a nested graph may not be best option but I was trying to emulate the image as best I could (thanks @pastelsky!)
rouzbeh84
on 2 Mar 2017
Mermaid and other similar markdown based libraries seem cool, although I
don't like the default styling they come with.
The diagram ends up looking too technical, and that will not help webpack
which is already perceived such.
Also, graphs may only form a part of the diagrams we would be using, so
keeping the look consistent with other diagrams is a challenge.
On 2 Mar 2017 12:22 p.m., "rouzbeh84" notifications@github.com wrote:
i can get back at it tomorrow a bit though. Would love to look into it a
bit further as a nested graph may not be best option but I was trying to
emulate the image as best I could (thanks @pastelsky
https://github.com/pastelsky!)—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/webpack/webpack.js.org/issues/469#issuecomment-283571981,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AIiCH_pdd0CSKZKo4YLgU66b_wo7gKGjks5rhmc8gaJpZM4LDlCh
.
pastelsky
on 3 Mar 2017
yea, sorry i didn't get a chance to style it up more. it does allow for pretty easy CSS styling though so it can be quite easily styled if you check out the bottom of the code in the link.
rouzbeh84
on 3 Mar 2017
Related: #473
skipjack
on 14 Jun 2017
@skipjack very related. I think mermaid is a very cool to for this kind of stuff. FYI the link above for the image is still live here
rouzbeh84
on 14 Jun 2017
@rouzbeh84 yeah and I'm definitely glad you started playing around with it -- this would be an awesome thing to push forward when we can.
Another related one: #487
skipjack
on 14 Jun 2017
Mermaid with custom styling looks pretty good. If we can get a good color scheme to go with all of the diagrams, that would be great.
pastelsky
on 14 Jun 2017
I was also thinking about @jaydenseric's point about the grungy look:
My thoughts on the graphic style is that it would not work well as SVG, due to the grungy smudges. Where possible all logos and diagrams should be SVG. I suggest changing the watercolor fills to a flat color, the borders should be ok as outlines.
Seeing as it's just an SVG, we should be able to do this using a single "grungy" png for the background that's used in each element with a different color filter, but only loaded once. Although maybe I've overlooked something about how mermaid works.
skipjack
on 15 Jun 2017
something like this could be a cool alternative to mermaid: https://www.jointjs.com/
hulkish
on 9 Jul 2017
@hulkish jointjs looks pretty awesome! do you know if they have a less expensive a.k.a free plan for OSS? I only saw a trial offered on their pricing page.
rouzbeh84
on 10 Aug 2017
@rouzbeh84 good question, I looked at this a while ago and was wondering the same thing. Also, I think there are some benefits to having a simpler text-based solution. I think it would be fairly easy to write a remark plugin (once we move to remark) that could use mermaid under the hood (e.g. remark-mermaid).
skipjack
on 10 Aug 2017
Working on porting to remark now (and a variety of other things) on the rebuild branch. And... looks like somebody beat us to the chase with a remark-mermaid plugin! I'll install and test it out on that branch.
skipjack
on 7 Jan 2018
Rebuild branch was merged some time ago, @pastelsky Are you still interested in adding these diagrams?
montogeek
on 10 Jun 2019
Related issues
webpack-bot
·
28Comments
nukeop
·
17Comments
skipjack
·
60Comments
simon04
·
17Comments
webpack-bot
·
27Comments