Optimize the proposal template

[SlugFiller]

Describe the project you are working on

Lurking in godot-proposals

Describe the problem or limitation you are having in your project

The proposal template has two cases of asking essentially the same question once.

The first is asking to describe the feature, and then asking to describe how it will work. Which is essentially the same thing. Even if the second specifies the use of diagrams, if diagrams are applicable, then it's better to just describe the feature with diagrams from the get-go. If anything, it makes more sense to first have the diagrams, and then explain how they would solve the problem, rather than the other way around. More often, it is clearer if each diagram is accompanied by its own description of what and why, making the attempt to make a hard division between describing the what and how, with no room for interlacing, not make any sense.

The other duplicate is actually the last two questions. These are basically the questions that ask "Are you sure this feature is needed, and is worth potentially making the export templates a larger download for every project, regardless of whether or not they use this feature?" From that perspective, I assume that the reason it's two separate questions is in order to make double sure.

However, if this is indeed the intention, then, as mentioned in https://github.com/godotengine/godot-proposals/issues/831#issuecomment-702500038, many simply interpret these as "Describe how much it will make your life easier if you didn't have to write this feature yourself, and someone else wrote it for you", instead of "Describe why there's no other way to achieve this other than changing the core engine".

Describe the feature / enhancement and how it helps to overcome the problem or limitation

The following box should, instead of being a full box, simply be a subtitle of the current box. It could be something like "Where applicable, provide pseudo-code, mock-ups, and/or diagrams, to better explain how your proposal will work. Fleshed out proposals are more likely to be considered for implementation".

The last two questions should simply be replaced with a hard "Explain why this cannot be achieved using GDScript or an addon in the asset library". Using the strong "cannot" instead of the soft "should", would make it clear that this is the point where people need to stop and rethink if their proposal is actually useful to the engine as a whole.

The point can be farther emphasized with a subtitle "Every extra feature carries an extra cost to all projects, especially those targeting web or mobile, even if that feature is not used. The general rule of thumb is that if it can be implemented as an addon instead of a core feature, then it should be"

It might be worth mentioning the Goost project as well, for something that can be implemented as a module, but is unlikely to be used in most projects.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

The uselessness of this box is self-demonstrating within this proposal.

If this enhancement will not be used often, can it be worked around with a few lines of script?

If the proposal template could be edited using GDScript, it would be simultaneously impressive, and alarming.

Is there a reason why this should be core and not an add-on in the asset library?

If it can't be done with "a few lines of script", then it can't be in the asset library (Unless GDExtensions exceed every expectation). If it can be, then the only reason is the asset library needing improvement, but that's a different topic.

At any rate, I've yet to see a serious answer to this box that hasn't been "Ditto".

[YuriSizov]

It's not applicable to every proposal, but it's not useless either. The first section can be used for high-level explanation, while the second can be used for the implementation detail. Depending on the way you express your thoughts it can be awkward, but you can also have the same issue with the "Describe the limitation" section, as you can naturally start explaining your solution alongside your problem.

So it can take a bit more effort and feel a bit more unnatural in some cases, but it's an important piece of information for most fully qualified proposals.

PS. Also keep in mind that some proposals predate the Discussion tab and would be considered low quality and converted to a discussion if opened today.

[SlugFiller]

@YuriSizov

The first section can be used for high-level explanation, while the second can be used for the implementation detail.

But, as I've said, you usually want the high and low level stuff side-by-side. For instance, if your proposal requires 3 new node types, you don't want to list them in one section, and then in the next section, describe what each one of them does. It makes more sense to interlace it, like mention a node type, the describe it, then the next node type, then the next description, etc. The division into two sections feels artificial here.

The order seems odd, too. For instance, it makes more sense to first explain how a feature works, and then explain how you would use it in your project to solve a specific situation.

In the rare cases where the high and low level explanations can and should be clearly delimited, the user can simply start a new paragraph, or use any of the existing markdown features like headers or horizontal lines to make that delimitation.

Although, to be honest, I would like to see an example where this delineation makes sense, and is used correctly. Because, looking at the top few proposals right now, at least one of the two boxes is usually filled with a one-liner, and they could very easily be merged into a single box at no loss to the proposal's clarity.

you can also have the same issue with the "Describe the limitation" section, as you can naturally start explaining your solution alongside your problem

And that would usually make sense, too. But at least the difference here is clear. Also, proposals where the problem and solution are intertwined, are usually ones that don't pass the "real project" test. That is, the problem is that the proposer wants a feature, and not that they are working on a project and hit some sort of roadblock. In the latter case, the proposer would usually have an easy time explaining where they got stuck, what they tried, and how they reached the conclusion that a change to the engine is their only option.

This can be better elucidated with a subtitle like "Explain what you tried, where you got stuck, and why a new feature is the only option. Proposals related to real projects and limitations are more likely to be considered than simply nice-to-have features"

[YuriSizov]

But, as I've said, you usually want the high and low level stuff side-by-side.

I mean, not necessarily. It highly depends on how you usually explain your ideas. And sometimes it's inevitable for the sections to intertwine, I've been there. I guess the layout was created with a specific kind of proposals in mind, which can follow the structure of "I work on X. I have this issue. I see it being resolved with this. Here's how it would work. Here's a possible workaround/I don't have a workaround. Here's why it needs to be core, and not addon/It can be an addon."

Not everything can follow that, but then users have no problem skipping/ditto'ing those sections, and we don't typically demand anything in such a case. The important thing here is to offer some certain structure over having a free form template.

[SlugFiller]

@YuriSizov I didn't suggest a free form template. Having a template is a good idea to direct users into a specific form for proposals, as well as direct them towards specific types of proposals, and even possibly pre-filter proposals that have little to no chance of being accepted.

What I'm offering is to fit the format to the way 90% of proposals are likely, and also, as far as I can see, are currently built. Like I said, I'd very much like to see this "perfect proposal" that fits the current format, but I'm not seeing it, and it's not like I've been browsing since yesterday. Even if you could find just one like it, it's clearly not representative of the larger use, and wouldn't become invalid if it added a separator on its own.

Like the engine itself, I think the proposal format should be minimally featured, while providing the large majority of the users what they need. If the vast majority of proposals use "ditto" for two of the items, then those two items are not serving whatever purpose they were intended for.

[YuriSizov]

You mistake the target audience of the proposals repo. It's not users, but contributors. A proposal issue is a document that suggests an enhancement or a new feature in a format that is useful to the people who are going to make it. It needs to be well explained and actionable, and these sections help to keep that focus in mind. That fact that there are many proposals that don't use the template well (or at all) is not too important in this case. Plus, as I've said, many currently open proposals do not qualify as proposals according to the rules of submission and should be converted to discussions (something that we didn't have access to when this was originally created).

So yes, the template should be optimized. But not with those who create proposals in mind. With those who are going to evaluate and implement them in mind.

[dalexeev]

I think this template is quite successful. Yes, there is some variability in which section you can put some paragraphs of your proposal, but I don’t remember a single case where someone abused formal criteria, if the overall proposal is written correctly. But perhaps section descriptions/placeholders could be improved.