Better first impression of the docs about redux-subspace HOT 10 CLOSED

So I've been working on building a gitbook to publish with gh-pages. I think it makes the existing docs much more usable with minimal changes, but I will also be adding a "Quick Start" section to the main README and each package README with a basic example of the syntax.

You can see what it currently looks like on my fork but I plan to get those changes make and have it up and running in the main repo ASAP.

from redux-subspace.

I'd say that the biggest thing that held me back from installing and trying this library out, was that I wasn't sure whether it addresses the same problem I was facing. In my opinion, the primary goal of the first paragraph of the readme is getting the reader to think "Oh, I see!", by explaining the problem and slightly touching the proposed solution. ducks-modular-redux's readme is a good example of this.

Making sure the user understands the terminology is also important. For instance, is "sub-application" as a term as descriptive as it could be? Should they be called something else instead? I'd argue that in most cases, the user doesn't consider them as being "applications" per se, but widgets (reusable components with logic) instead.

To summarise, the purpose of the main README is to convince the user that this library will make his/her life better. One could even argue, that this library has the potential to be quite paradigm shifting amongst react/redux users, providing a new higher-level concept to regular components.

Lack of code snippets was definitely a big one for me as well. Basics -> Creating Subspaces seems to be the first page with a code example, and at that time you've already gone through ~4 pages of documentation. "Show, don't tell" encapsulates this quite well, and I would definitely have code examples already on the main README page. It should be a react example, since most likely >90% of the readers would be using this in conjunction with react.

Even though I kinda like the granularity of the readme (and it's partly caused by the subpackage structure), it might make sense to merge some of the pages together. As an example, we could combine all API methods listed here and just have one .md listing all of them. This also makes searching stuff a lot easier.

from redux-subspace.

Lack of code snippets was definitely a big one for me as well. Basics -> Creating Subspaces seems to be the first page with a code example, and at that time you've already gone through ~4 pages of documentation.

I think this is my biggest concern with the docs at the moment. To ask users to invest 4 pages of docs before they even get a sample of what the API looks like is a pretty big ask.

Making sure the user understands the terminology is also important. For instance, is "sub-application" as a term as descriptive as it could be? Should they be called something else instead? I'd argue that in most cases, the user doesn't consider them as being "applications" per se, but widgets (reusable components with logic) instead.

This is a pretty good point too. When redoing the docs, I purposely moved away from "micro-frontend" because I felt like nobody would know what we were talking about either. Personally, I'm not a big fan of the term "widget" (for no real reason other than I think it sounds silly), but I agree that many users wont think of parts of their applications as sub-applications. Mark Erikson recently referred to redux-subspace providing "portal" (possibly "portlet", the audio quality isn't the best) functionality. I'm not sure if that is a better or more well known term, but I liked the way it sounded.

from redux-subspace.

Yup, I wouldn't go with widget either to be honest. To me portal sounds a bit similar to what wormhole provides and it can be confused with react-portal. Portlet doesn't really resonate with me, but it might easy be it's just because I'm not a native English speaker. Sounds like something from Java/Spring 😄

If I've understood correctly, in Android world "fragment" is used to describe something similar to what subspace achieves, but that's also a reserved term in React land. What do you think about "reusable container"?

from redux-subspace.

yeah, "portal" isn't right for me either (and I hope "portlet" was just bad audio because it means nothing to me).

I quite like "fragment", but hadn't heard of the React version before you linked it, so unfortunately I think it's out.

"reusable container" is not bad, and has some good familiarity with "Container Components" in React. It potentially feels a little too generic and get clunky to use in sentences. I also feel like it only covers one use case (reusability), and doesn't hit the initial use case subspace was created for (isolation).

perhaps just calling them "sub-components" is more familiar and generic enough fit into most contexts. I'm just a little worried it's too "Reacty".

from redux-subspace.

"Sub-components" sounds good to me. For some reason I'm not too worried about it being too reacty, since at least from my perspective React users are the main audience for this library.

A bit off-topic, but started thinking the other day, that it might be a good idea to try to get a mention of redux-subspace to Redux's Isolating Subapps documentation. Maybe not something that should be done straight away, especially considering that we still want to improve the docs and that subspace isn't that widely adopted yet.

from redux-subspace.

I'd love to get more of a presence in the redux docs, but not sure what the etiquette is for adding my own library to that sort of thing. Maybe @markerikson can advise us on how to go about it. I know he wants to completely revamp the ecosystem page of the redux docs as well so perhaps we can help out with that too?

from redux-subspace.

At least "Async Actions" page seem to contain links to Redux enhancers, so I'd guess it's fine. We can always try :)

from redux-subspace.

Yeah, the word I used in that talk was "portlet" (see https://en.wikipedia.org/wiki/Portlet and http://archive.oreilly.com/pub/a/java/archive/what-is-a-portlet.html for examples).

redux-subspace is definitely one of several libraries I'd like to highlight more prominently just based on my own opinion of quality, use case, and potential benefit to the community, but I haven't had time to start actually trying to tackle rewriting the "Ecosystem" page.

Y'know, if some people out there in the community wanted to volunteer to help rework that page based on my directions, that might get it done faster.... :)

And yes, I do think that the main README for redux-subspace should have a good summary of the overall use case of the library, and examples of at least the syntax and usage for the core and React packages.

from redux-subspace.

Now that #64 is merged, I'll close this, but if you feel there are any areas that need improvement, please feel free to drop a comment here, open a new issue or submit a pull request (my preference).

from redux-subspace.