readme-scope-details: Update readme with scope & rejected ideas #7
Conversation
There was a problem hiding this comment.
First of all, thanks for the contribution!
There's some good changes here, but overall it's not the right style for FOSS documentation.
I've added several comments about specific changes, but overall, I think the main thing is just being less formal and using Active Voice wherever possible.
Lmk if you have any questions for me. Thanks!
| complex and interactive web applications, but they come at a cost of increased | ||
| complexity, and most of their functionality is not necessary for the majority |
There was a problem hiding this comment.
Why was this comma removed? IIUC, the phrase after the , and here is an independent clause, so the comma is needed.
If it feels like a run-on sentence, we can remove the comma and start the sentence with a capital. E.g. . And most of their functionality....
| large framework, only using the features of the language, but there aren't a | ||
| lot of options right now. | ||
| were a productive workflow for developing front-end applications without needing to | ||
| utilize any large framework - only using the features of the language - but there aren't |
There was a problem hiding this comment.
Three things here:
- Was -> were is a good catch.
- I don't think we need to change
anytoneeding to utilize any. This feels overly formal. The README should be mostly informal, but not quite conversational. Ideally, Active Voice should be used wherever possible, but also complex sentence structure is generally discouraged for FOSS documentation since a lot of users are not native English speakers. - The use of hyphens is strange. I don't know of any English grammar structure that uses hyphens for clause separation. I think these should either be changed back to commas or semi-colons, but probably commas. The grammar rule that applies here is that the
only using the features of the languageportion is a sentence fragment that is not essential to the overall meaning of the sentence, so it should be within commas.
- This is probably just a bad sentence in general. When I start worrying about whether to use commas or semi-colons, that's usually an indication that I just need to rewrite the sentence. What do you think of replacing this entire sentence with "For these reasons, it would be great if there were a productive workflow for developing front-end applications with only core language features and no framework, but there aren't a lot of options for that right now."?
|
|
||
| Native Web Components are great, but they have a runtime cost that results | ||
| in content reflow unless template tags are used in the HTML page that the component | ||
| in content reflow unless template tags are used within the HTML page that the component |
There was a problem hiding this comment.
I think we can leave this as in. I'm not sure if it's 100% grammatically correct, but it feels less formal and more direct than within, so I would prefer this style for a FOSS project. :)
| is loaded into. This is because the component has to parse and render the HTML | ||
| it owns at runtime unless the template is included in the consuming page, which defeats | ||
| the purpose of the modular components. | ||
| any performance gains of the modular components. |
There was a problem hiding this comment.
This can be left as the purpose. The runtime performance hit is a problem, but the which defeats part is referring to the template is included in the consuming page portion of this sentence. In other words, including the template tags in the consuming page to avoid the runtime performance hit of native web components defeats the purpose of modulr components, which are intended to modularize HTML fragments to make web dev simpler.
Reading through this more carefully, I can see how this sentence is confusing. If you have a better way to communicate that meaning, feel free to change it, but I don't want to emphasize the "performance gains" of Modulr too much since that's not really the point, and the performance really depends on the JS that the user writes anyway. :)
|
|
||
| I'm sure there's a way to make a performant web app with some shadow dom trickery, but | ||
| There is likely a way to make a performant web app with some shadow DOM trickery, but |
There was a problem hiding this comment.
I wrote this sentence from first-person because I wasn't really expecting anyone to contribute to the project for the most part. This should probably be changed, but the use of Passive Voice is strongly discouraged, so I'm not sure if There is likely is a good option here.
Generally, FOSS projects use we to refer to the project/devs and you to refer to the user of the software in documentation. In this case, the sentence here is a personal statement. I'm indicating my own lack of knowledge of the Shadow DOM, and the statement that I make about it is completely speculative. For this reason, I don't think that it would be good to use any language that indicates that this statement is on behalf of the project or other contributors.
I think it's probably fine to just remove this sentence since it's really just a statement that I personally made this script without really exploring the shadow DOM and that's not really necessary information for a user of this project.
What do you think?
| @@ -59,14 +60,48 @@ To install, simply download the modulr.py script into your project's root direct | |||
| Run the script with Python: `python modulr.py`. | |||
|
|
|||
| Modulr requires Python >= 3.12 because of the use of `Path.walk`. I plan to eventually | |||
| package Modulr as a standalone commandline app, but for now, you will need Python 3.12 | |||
| package Modulr as a standalone commandline app; but for now, you will need Python 3.12 | |||
There was a problem hiding this comment.
Why is this a semi-colon?
Semi-colons separate independent clauses that are not joined by a coordinating conjunction, so this should either be a comma, or we can remove the but and use the semi-colon. E.g. "I plan to eventually package Modulr as a standalone commandline app; for now, you will need Python 3.12."
Another option is to simply separate the sentences: "I plan to eventually package Modulr as a standalone commandline app. But for now, you will need Python 3.12."
Also, since we are changing the tone of the README from a first-person perspective to a project perspective, I guess we should change I plan to We plan.
What do you think?
| installed in order to run the script. | ||
|
|
||
| If your system doesn't come with 3.12, the easiest way to get a different version | ||
| installed is with either | ||
| [Hatch](https://hatch.pypa.io/latest/install/) or | ||
| [Pyenv](https://github.com/pyenv/pyenv?tab=readme-ov-file#installation). | ||
|
|
||
| ## Project Scope & Limitations |
There was a problem hiding this comment.
This section is very formal and is entirely in the Passive Voice. It needs to be rewritten to use Active Voice.
Using we to refer to the project/devs and you to refer to users is helpful for this kind of writing. Lmk if you have any questions. :)
| times on the same page will inevitably lead to selection collisions. Any suitable solution | ||
| to this challenge will result in a leaky abstraction, which runs counter to Modulr's goal | ||
| of improving maintainability, so this project is built with the philosophy that Modulr | ||
| components are single-use within a page. |
There was a problem hiding this comment.
This paragraph misrepresents the goals of the project.
There are a few things that I think need to be updated:
- The purpose of the project is to allow modular HTML fragments just like we can import JS or Python modules. Not necessarily to improve maintainability but to make pure JS/HTML/CSS maintainable in the first place. I think this is one of the things that I didn't communicate very well with the original README. :)
- I think we should remove any mention of copy-paste since that gives a very different impression of what the workflow would be like. This could scare off a new user. :)
- The portion about DOM manipulation mentions selection collisions and leaky abstractions, but it doesn't really give any context as to why those things happen, so it isn't clear why this is a problem based on this paragraph. I think that including some context about JS being global at the page level and how this causes the user to have to think about context outside of the modulr component when multiple components are allowed would help clarify this. It should still be as concise as possible, but I'd rather have a long paragraph than risk confusing the reader. :)
- I'm hesitant to use wording like Any suitable solution. I don't know if that's true or not. I would prefer wording like Current solutions or We couldn't come up with a solution that didn't result in a leaky abstraction. In general though, I would prefer not to have very broad statements about things like this. It's possible that I could actually come up with a very nice solution to this problem with enough time, but I didn't want to invest that much time or effort into this project since it's mainly just a personal tool and I have a lot of higher priorities right now. Does that make sense?
- Since modulr's goal is allowing the use of modular HTML fragments in frontend dev, we can change Modulr's goal of improving maintainability to something like Our goal of allowing simple code reuse at the HTML level. (Active Voice). :)
- Modulr isn't built with the philosophy that components are single-use within a page. That's a consequence of this specific feature experiment. I think we can leave out this last part all-together.
| components add more overhead to your code, and while how/when to break up components is (to | ||
| some extent) a stylistic choice within some front-end technologies, this process easily devolves | ||
| into code that is difficult to compose and reason about. Not supporting this feature should help | ||
| encourage components that are easier to maintain. |
There was a problem hiding this comment.
This paragraph doesn't really give any context around what a "component" is in a SPA or Native Web Component. I think that it's probably helpful to mention these other tools so that framework users who might expect Modulr to be the same will know not to just use the same patterns, but I would rather focus on what Modulr components are as opposed to what they aren't.
Some of the wording here feels a bit vague. Reducing boilerplate and overhead is great, but how does modulr do that, and why does allowing nested components prevent that?
I think including an example like I did in #5 would be helpful for providing some of this context. Also, I think the comparison to inheritance vs composition in OOP is probably something that a lot of the target audience of this project would be familiar with, so if you can find a concise way to draw that comparison, that might be enough to clarify these things.
Overall, I think that this section needs to somehow communicate that modulr components are intended to be more course-grained than SPA or Web Components. Specifically, they should not operate at the element-level. I don't want to overemphasize that they are structural sections since they can also be used for things like the Mathjax component I showed you offline. That component could be thought of kind of like a Mixin in OOP. It could easily get out of hand if you used that kind of pattern all over the place, but for certain things like adding LaTeX support to a page, it is a really nice pattern to use.
Does that make sense?
| This runs very closely with scope item number two. Due to many of the same reasons why | ||
| nesting components adds complexity to projects, passing properties to components is another | ||
| major source of complexity in your code that this project avoids. | ||
|
|
There was a problem hiding this comment.
I think we can just remove this section all-together. Props are a product of SPA frameworks, and this project only uses the core language features and web standards. I don't think we need to mention not supporting things like "Props". Also, I never actually considered it since I personally think that Props are an anti-pattern even in SPAs, so I don't think it fits into this section about features that were explored and axed.
It's kind of like "state management". That's a problem that SPAs created that doesn't exist in standard tech, so there's no need to mention it in the context of this project.
If a user opens an issue about supporting Props, I'd probably just respond with "this isn't React", so I'm not really worried about this specifically.
I guess I just don't really want to explain how this project works in terms of some framework or other tool. I understand that it can make it easier for some developers to pick up on the concepts, but it's kind of like learning JS concepts through React or Vue concepts. It's kind of backwards, if that makes sense.
|
Closing due to inactivity. |
This PR is designed to address #5.
Included in this PR are: