feat: Folder inversion — source files in root folder, Bridgetown support files in subfolder

[jaredcwhite]

feat: Folder inversion — source files in root folder, Bridgetown support files in subfolder

[sandstrom]

@jaredcwhite I don't agree, but that's fine 😄

I think when it comes to making a framework approachable, effort is better spent on documentation.

Don't write code to solve problems that are easily solved by documentation. Because documentation is much easier to maintain, and are often just as good at solving the underlying user problem.

For example, if people have trouble finding a sub-directory, just write it in the docs.

Also, you're unlikely to have time to work on low-priority issues like this. Adding them to the "backlog" just adds noise, and time will always be the constraining factor anyway. It's better to "say no" to more things, and avoid adding too much functionality into the core framework.

Anyway, thanks for your work on Bridgetown! We like the tool and are happy to sponsor your work on it.

[jaredcwhite]

Let's try to keep the conversation on topic for this particular feature. Thanks.

[sandstrom]

My personal opinion is that inverting the structure isn't worth the time, nor the churn (and juggling two setups will just add extra work code paths and complexity to the framework), with little to no user benefit.

Learning to look in a particular folder (src) to find the "content" is a trivial thing, and I've never heard of any project or framework where that has been seen as an issue.

Broader point

More broadly, I think Bridgetown as a framework should deprecate and remove stuff that's rarely used, simplify internals and narrow the overall scope.

It's always more fun to add features, but Bridgetown already have most stuff that one needs from a static site generator (and what it doesn't have, people can code themselves using appropriate hooks).

So things like:

• Erb as default template language (#705)
• Decouple front-end logic from Bridgetown (#609 (comment))
• Retire Bridgetown::URL (#402)

[jaredcwhite]

Oh sure, it's definitely low-priority. But I'm always on the hunt for interesting ideas to make development more approachable for newbies or for other types of projects which don't fit under the typical umbrella of a site project.

[brandondrew]

I've worked on so many projects where devs don't write docs and tell me "I guess you're just not as smart as the rest of us." when I don't understand their code.

I probably largely agree with you about the need to write comments (or documentation) for code that is not immediately clear, but that's a completely unrelated situation. These 2 things are not the same:

1. documentation about a product for users versus code that makes a product simpler and reduces the need for documentation
2. documentation about code for developers versus no documentation

Therefore arguing for the need for comments (or other documentation) to explain code has no bearing on whether it's better to use documentation rather than making products (software or otherwise) simpler for the user to use.

Even though Bridgetown is probabaly mainly used by developers, the market for SSGs is by no means limited to developers. I think it makes sense to make an SSG as easily usable by as many people as possible, with as little complexity as possible—without taking away any of the features that only developers will use.

[brandondrew]

I think when it comes to making a framework approachable, effort is better spent on documentation.

Don't write code to solve problems that are easily solved by documentation. Because documentation is much easier to maintain, and are often just as good at solving the underlying user problem.

Wow I have a completely different view from Sandstrom.

When I create an app, I want it to be as intuitive as possible. I'm thinking now of end users—and of course it's different with something built for developers—but with end users I feel like I've failed if they need documentation. My goal is to never need to give end users any documentation at all—I want them to be able to sit down in front of the app and just use it.

So although tools for developers are necessarily more complex and there's really no way to avoid documentation, I still feel it's better to make a problem go away by writing code rather than documenting what to do to solve the problem.

Of course everything is a matter of trade-offs, and so of course there may be exceptions when some code will be hard to maintain, but documentation is notorious for going stale, so I would personally lean away from the "documentation over code" approach. I think the elegant solution is the ideal, and that is likely to have more happy users.

Just my 2¢ 😊

[alexfinnarn]

I'm in the "better to solve with documentation" camp myself, and I don't understand why developers want to avoid writing documentation or comments when the code is mainly for us to read and understand. I've worked on so many projects where devs don't write docs and tell me "I guess you're just not as smart as the rest of us." when I don't understand their code.

If you are building a physical product, is your goal to never ship a manual? If so, you can only sell very simple tools where no instruction is necessary. Otherwise, people need a manual. Some will never read it, but it will help others to maintain and not ruin their purchase. I am a weirdo who always reads the manual before operating anything so I would be mad if you shipped something without documentation.

But as someone looking into this project without much knowledge of it or its history, I would not focus on these types of features. My first impression of Bridgetown is that it seems to have a lot of features and options I would need to make decisions on. This would be yet another decision to make: do I want to have my source at the root or not?

For example, when I saw on the getting started page:

Prefer ERB or Serbea over Liquid? Prefer Webpack over esbuild? Prefer Sass over vanilla CSS? Read about the available new options here.

I thought, whoa I got some reading to do before I even understand more of the project. Of course, it all comes down to what the maintainers want the focus to be, but at first glance, there's plenty already to impress newcomers IMHO.

Just wanted to add my 2 cents since I feel very strongly about not solving things in code when you can just write documentation. I am currently working on an issue at my day job where documentation would suffice, but I am being forced to make the application more complex and brittle.

[alexfinnarn]

I still don't understand your point exactly. I also don't think Bridgetown will ever be used by non-developers unless a commercially hosted option pops up.

But after reading more about Bridgetown, now I think "Go for it!" This project is way more complicated than what I need so I won't be using it. I simply don't need all the current features let alone what will be added. For context, I'm just looking to have something wrangle markdown files and no need for a static export. I got to this issue from the Discord server which was linked from the Community section.

After reading https://www.bridgetownrb.com/docs/philosophy I think it makes more sense for this project to try out fancy ideas since the goal isn't to "focus on maintaining extensive backwards-compatibility and a paired-down feature set". Who knows, this idea could look like a killer feature to some. So, I'm not your market, I guess, and that's okay.

[jaredcwhite]

As much as I'd like to go off on experimental wild goose chases (because it's fun!), we have so-o-o-o much on our plate right now to get Bridgetown 2.0 underway and all the follow-up tweaking involved, I think we can close this. Always happy to reopen at some point down the road.