Feedback on Examples in Docs

[acolombi]

A thought on the code examples throughout the docs. They are helpful, but something that consistently makes them a bit tougher to use than I'd like is the way they're factored. They're designed like you would design real software: DRY, modular code that makes maintenance of the code as minimal as possible. The problem is that because they're so well factored, it means I need to navigate through multiple files, and potentially understand your class hierarchy to really grok an example. It's basically impossible to copy example code at times, because it depends on libraries within the example code base.

I think this is a case where copy pasted code, that created self-contained examples, would actually make your code more useful for your audience.

[acolombi]

After this initial request Gilad and I had a conversation over email:

Thanks for the feedback Andrew! My thinking behind the factoring (aside from the epic DRYness) is that all a user really needs to see is renderExample and event handler, which all live in the example class itself: what does the JSX look like for this component, and how do I hook it up to my state? The options and example frame shouldn’t be necessary for understanding how it works when you view the source. But at the same time, I’ve never been able to approach the examples as an outside user.   We’re planning to redesign the example frame in a coming release and I’ll see what I can do to simplify the code. Would you mind filing an issue to track this request?

My response:

Thanks, Gilad. It's easy for me to imagine greener grass, but given that I haven't actually refactored the code to be how I suggest, I could be wrong. I can easily imagine boilerplate around setting up the example being a distraction.

I think my main frustration is that the components don't extend React.Component. It just throws me off immediately, and makes me wonder how much context I need to learn just to understand the example. Maybe there's a way to get the DRYness you want with a Higher Order Component, rather than a new layer in the class hierarchy?

[adidahiya]

generally +1 for the idea of higher order components, or simply component composition, instead of class hierarchies

[dmackerman]

This is interesting, because I've noticed that same thing. But on the other hand, I've learned a lot from looking at the entire Blueprint codebase. You can tell how much effort and planning has been put into the architecture, that it's been a great learning tool for how to write well formed React code (and we don't even use TypeScript).

If there's one area in which I could recommend more documentation would be the SCSS stuff. You guys clearly spent a lot of time architecting the mixins, structure, etc.

I would say the more complex examples are hard to grok from first glance at the examples, and don't do well for copy/paste especially because of Typescript. A lot of the code would seem simpler without verbose type annotations, but also understand how that isn't a priority at all for the project.

[acolombi]

I just ran into an example that reminded me of this issue that I filed: https://github.com/palantir/blueprint/blob/develop/packages/docs-app/src/examples/core-examples/radioExample.tsx. I wish the implementation of handleStringChange was immediately obvious from the example, rather than imported from outside blueprintjs/core.