hunterae
commented
5 years ago Hey @davestewart , One small clarification: whenever I mention "landing page" above, I'm referring to the documentation landing page, whereas it appears I refer to the Github Readme page as either "Github landing page" or "Github page" or "Github" readme. Sorry if this causes any confusion.
Also, you mentioned in reply on the Reddit thread, there are definitely discrepancies between the Github Readme and the documentation site root page. I came across one possible solution for dealing with that problem when I was figuring out how to assemble my own documentation for my VueTableFor plugin (I know that documentation itself needs a ton of work; also, I just realized I never pushed that change so you'll see a commit for it today). Essentially (and assuming you're generating your documentation using Vue), you can have your main documentation component import your README.md file using vue-markdown-loader and then render it. See link 1 and link 2 (Note: I had to import some specific css styles to display the Markdown nicely).
For purposes of credit, I saw that approach used on the vue-fullscreen plugin documentation.
Regarding the "@" syntax in paths, as you mentioned, a switch to only using "." would probably be the best case scenario. For the short-term, I'm actually fine with the "@" syntax (and was fine using it once I understood what it was doing). My brain just found it hard to parse the visual example in the documentation of "bar/baz@a.b.c". I remember looking at that several times previously asking myself, ok, what's the module, what's the state field, so then what's "a" and "b" and "c". It took me an embarrassingly long time to internalize the information. I'm sure you're already thinking along these lines, but perhaps V2, as well as the documentation, can support both syntaxes. That way, you cater towards the people who view it as an object lookup chain vs the people who want to be explicit in their sub-object lookup. I think both approaches could be easily justified.
pacific202
Follow up on comments left here:
Hey Dave, First off, let me say great work on this plugin. It is truly awesome, and I am very grateful to have found it instead of attempting to build one myself. Also, I in no way meant offense about the state of the documentation. Now that I understand how to use the plugin, it is a great reference and I know exactly where to go to find what I need.
That said, I have the following suggestions:
1) The overview on the Github page, as well as the introduction section within the documentation both jump right into an example use of paths. The problem is that somebody looking at this the first time really isn't sure what to make of that path based syntax, particularly the @ sign. While I 100% agree that the path based syntax is one of the most powerful uses for the plugin, I wonder if the documentation would be easier to understand if the examples of path syntax fell further down in the page. Instead, I would focus on one of the main reasons I'm guess a lot of people found your plugin in the first place - i.e. the elimination of boiler plate code that we all found to be overkill in the setup of Vuex. Perhaps a side-by-side comparison of the same vuex store, one with the original Vuex boiler-plate code next to the new, cleaner, compact code in setting up the same store with vuex-pathify. If you went this route, you could add headers over the two columns like “Instead of” and “Do this”. The article I mentioned in my original comment does a good job of explaining what exactly you’re replacing and simplifying by using vuex-pathify.
In preparing these suggestions, I just realized you do have a Vuex comparison on the GitHub landing page. I cannot find this anywhere on the documentation site. I think it needs to be pretty front and center as described above
2) The path-based syntax was largely unclear to me initially, and I believe the biggest barrier was the use of arbitrary words (albeit computer science words) like "foo", "bar", and "baz", as well as "a", "b", and "c". I think it would go a lot further if you swapped those variables for a more realistic scenario. Off the top of my head, perhaps you could use something like a "user" object, which has nested fields and objects, like "email" as a string field, "favoritePosts" as an array, "firstName", "lastName", etc. Perhaps a root-level state field could be something like “loading”
3) I wouldn’t use the “…” in the opening diagram (the one with all the “foo”s and “bar”s etc) as this is the first demonstration of the path syntax. I mentioned above using more realistic variables. I would also put realistic values in there. So perhaps the root-level state could be something like: “state: { viewport: { width: 1440, height: 700 }”. Then, in the example paths, you should use both “viewport” and “viewport@width” and demonstrate that you can both access a state field and / or access a property within a state field.
4) For the “get”, “sync” examples, I’d once again show the original vuex syntax and then the new improved syntax.
5) I’d add “call” to the landing page and GitHub readme examples, since that is one of the key components that is being replaced in Vuex. (Upon examining further, it does appear you add it further down in the page below the more complex sync examples - although ‘call’ does not appear on the landing page for the documentation). I’d move this up with the section where you have “computed: { products: get(…”. Also, within that section, I’d make it more clear that “get” injects a store field into your components, “sync” injects a store field into your components and also automatically syncs changes back to the store.
6) It is unclear on the home page what “get” vs. “sync” does. The way the examples show it, it might falsely lead someone to believe they use “get” when it’s a simple field like “products” and “sync” when they need to access properties within a field like “filters@category”.
7) For the more complicated examples of sync on the homepage, I wasn’t sure what was happening when one does something like “…sync(‘filters@sort’, [‘order’, ‘key’])” (or the object based example, or the wildcard example), I was not clear what ‘order’ and ‘key’ were in that example; I now know that those are fields that would example on a sort object which is a field within a filters object. If you standardized your examples throughout the documentation, it would make that syntax a little bit more clear. I also wonder if it would make it more clear if you included the sample content of an actual Vue components on the root page that could use the injected “get”, “sync” and “call” actions. If that existed, even as an image on the homepage, it would go far in terms of clarifying the overall use of the plugin. It may also be worthwhile moving these more complicated examples either off of the landing page or further down in a separate section.
8) It is unclear on the landing page what exactly make.mutations is doing. Is it adding the getters and setters for me or just the mutations. I found myself further confused later in the documentation when it introduced the other methods like make.getters and make.actions. If I only use make.mutations, am I also getting the getters and actions, or am I dependent on using the store.get and store.set calls if I don’t generate the mutations.
9) I’d move store.get and store.set further down in your documentation on the root page, as it would seem this is a more specific use case that 90% of the time won’t be necessary, and perhaps doesn’t even need to be on the landing page.
10) It may be worthwhile to add some links to the more advanced documentation for specific topics off of the landing page, such as full clarification of the path syntax, etc.
11) I still find myself confused by the nature of the demos that are linked off the documentation. As far as I can tell, you are allowing one to edit the code which generates the documentation. If this is true (and is dynamically allowing one to edit the actual code that builds the documentation), then that’s really awesome and definitely worthy of a blog post / medium article describing how you built that. However, I find that as an example overly complicated for understanding how to use vuex-pathify. The simple demo is better, although I think it would be best if you could pair it does to a single file or two to three files that are barebones pieces focusing on the setup of the vuex store with vuex-pathify, and then the injections of “get”, “sync”, and “call” into a sample components which could be something as simple as an input field and a greeting using the value injected from the store and set from the input field using sync. I tried to build a simple example in Codepen but couldn’t run it because it appears all the dist files for vuex-pathify on unpkg are using “require” syntax (see #13 below). Here’s the beginnings of a simplified example: https://codepen.io/hunterae/pen/dBZVKp?editors=1011
12) I don’t remember where I clicked this particular demo link, but wherever there is a direct link to https://codesandbox.io/s/github/davestewart/vuex-pathify/tree/master/demo, the running demo lands on a home page that has links to the various demos “Simple”, “Main”, “Nuxt” (and “Docs”). The links in the demo browser do not work. (I think the direct link is off of the Simple Demo example when one clicks the “feature demo” link, i.e. off of this page https://codesandbox.io/s/github/davestewart/vuex-pathify-demos/tree/master/simple. It also appears to be linked directly from the “demos” page as the “online” link)
13) Not specifically documentation related, but it would be nice to have the build script build a version of the plugin that can be used directly from the browser. It seems like the minimized file uses the “require” syntax which then fails when attempting to include from somewhere like Codepen (the specific offending line is "var createDecorator = require('vue-class-component').createDecorator;”)
I may be able to come up with some more suggestions, but that’s probably a good start. Plus, I need to start work. Hope you find these suggestions helpful.
Andrew