Proposal & Review Process -- Having a major idea gauged before implementation

[Anticept]

Preface

So you want to contribute to the Paradise SS13 project? Awesome! There’s a couple ways you can go about this.

You could just simply throw up a pull request on https://github.com/ParadiseSS13/Paradise and wait to see what happens to it. This is great for simple changes and bugfixes. If it gets turned down, then you haven’t spent much time on it.

However, If your intention is to contribute something that you are spending a lot of time on, then STOP for a moment. Remember that staff are under no obligation to accept your contribution. We don’t want to see you spend a lot of time developing your idea, then have it shot down because it doesn’t fit what Paradise is trying to accomplish. We don’t want you to burn out because your code got rejected. That’s why there’s an OPTIONAL process you can use before you start laying the first lines of code, called the Proposal & Review process.

In essence, this is more than just a 'suggestion'. A proposal is an idea you've taken beyond just the idea stage, you've organized it, considered its implications, and given it a lot more thought. It's become a PLAN.

A proposal lets the staff and you about your idea a bit. If they like your idea, then you are far less likely to waste large amounts of time developing, as you’ve already got your foot in the door. You might even get help from various people to implement it!

Writing a proposal really gives you a chance to think about and organize your idea. Often, an idea that sounds good in our head is under idealized circumstances, and once you really start considering implications, those circumstances can often fall apart. You really need to give some maturation time to a major idea, and a proposal is one way of doing it.

Remember. Writing a proposal is OPTIONAL, but HIGHLY RECOMMENDED for more than bugfixes and simple changes. Ultimately, it’s your own time that is wasted, but that’s still valuable time to you, and to the project. Time that you spend on an idea that isn’t well received, is time that could have been spent on something that IS well received.

 

This is the recommended way to go about writing a proposal.

Each step assumes the previous one was successful.

1. Draft a proposal. Encourage feedback during the drafting process from your trusted peers. Create a few small, simple examples if you can, like with sprites.

   • Don't do drafts openly. This is your DRAFT. It’s not even close to ready, and throwing it out in the open at the start of an idea is bad. You’re going to end up with people throwing wild ideas at you, and by the time you are done, it’s not even going to resemble what you might have had in mind. Design by Committee often doesn't work. You're having dozens, maybe hundreds of players scrutinizing the shit out of it with little actual vested interest.

   • You're going to rally a bunch of support for something that might not honestly even be possible due to technical limitations. If it gets shot down, you're going to cause a bunch of rabble rabble.

   • Just don't do drafts openly unless you are TRYING to start a shitstorm, and don't be surprised if you get shut down because of it. This almost never ends well.

2. Refine your draft into a proposal for review by staff. I would even suggest having at least a partial development plan done if you expect to have any points scored with the maintainers. Listen to their feedback, refine your proposal, or shrug and be thankful you didn't waste a whole bunch of coding time.

   • You need a WELL DEVELOPED proposal. You are being GIVEN their limited time, so make full use of it. Submitting an amateur proposal isn't going to reflect well on you or your idea, and you shouldn't be surprised if it gets shitcanned because it looks like it would have been better done submitted in crayon. Examples are included later in what constitutes a good proposal. READ THEM!

   • You want the first section to clearly address what it is you are adding or changing, and YOUR reasoning for doing so. Don’t leave it up to staff to try and guess why you are making this change. This seemingly innocuous part of a good proposal is actually quite important!

   • Include a development plan. Can development of your idea be broken down into small, testable chunks? If so, DO IT! You WILL save yourself a LOT of heartache. Make sure the staff see your development plans too!

     • When you try to make really large changes that take a lot of time to finish, you’re going to end up with merge conflict problems. Breaking things down into small bits avoids a lot of this, and also makes it easier to hunt down bugs.

     • This also makes things much easier for people to contribute development time to your idea as well.

3. Now for the hardest part. Submitting the proposal for PUBLIC consumption. You need to convince the playerbase that your idea is a good one, while still staying within your vision and what the admins and maintainers approved. The staff should monitoring and participating as well. Someone might make a really damn good point that causes you to do a big change, and you WANT staff to be part of it, because again, they are the ones that ultimately decide if it’s go/no go. Take the feedback you get, and further refine your proposal.

   • By this point, the design is largely already done, so much of the discussion will revolve around refining the idea, rather than getting a ton of random suggestions. That’s another reason why you don’t publish your work in progress draft openly!

4. Begin development! You're starting the longest part of this road! But the light at the end of the tunnel is within sight!

5. Submit each chunk for review and testing, if possible, as PRs on github.

   • Your idea, or portions thereof, could still get scrapped. Don't write off the possibility. Technical limitations can be encountered while implementing your idea, causing the whole thing to become infeasible. Or there’s a shift in philosophy and now your idea no longer fits the paradigm. That’s why you are encouraged to break it down!

 

Tips for writing a good proposal:

First and foremost. The less people have to assume, the better. It’s your idea. You need to convey it. If you leave gaps for other people to fill, they WILL fill it, and quite possibly with details that you didn’t make or intend.

So that said, spend some serious time thinking through your proposal. For relatively small changes, this will still go relatively fast. For major overhauls, it’s strongly recommended you spend some serious time on writing up a good, solid proposal. You’ve already convinced yourself it’s a good idea, but now you have to convince others.

 

Organization, spelling, and grammar

You want to know the biggest thing between a good and a bad proposal? Presentation. If it’s well organized and doesn’t look like a 3 year old wrote it, people will spend more time reading it. That’s what you want, right?

Imagine you are the hiring manager for a company, and you got a hundred applications. Chances are, you won’t even get past the first section of a resume if it is just a bunch of random things put on it that doesn’t flow. That’s the fastest way to get it sent to a recycling facility, and the applicant back applying for more jobs. On the other hand, even if the content is only okay but it LOOKS great, you, as the hiring manager will likely still spend the time skimming the first page! That’s just human nature. Fight it at your own risk.

Remember. You are GIVEN staff’s limited time to look at your idea. Make it count. If you are crap at writing, find someone who believes in your idea who can help. Hopefully the way this document is written can give you some ideas on how to organize your proposal, because it was designed to do exactly that! If you follow the chapter “Recommended elements to include in your proposal,” it’s basically an outline!

 

 

Recommended elements to include in your proposal:

A Super Quick Summary What Your Proposal is for

Keep it short and sweet. Details come later. What, at a glance, are you trying to do? Are you trying to add a sepia display filter for vintage feeling screenshots? Are you trying to add an item that allows double-jumping? Are you trying to add enumeration support to the code? These are already examples to show what I mean by a super quick summary. This could even be your headline! The important thing is to keep it a one or two line lead-in for your proposal.

 

Your Reasoning and Justification.

That is, your OWN reasoning and justifications. Don’t insert words into other people’s mouths. It’s a great way to start off on the wrong foot. You can still include links and sources to back up your claims (including links to other’s opinions), just don’t speak for anyone without their permission. Stick to what they’ve said if you are going to include them in your proposal.

Examples:

 

Bad:

• I’ve been talking to everyone, and we’ve all agreed that this part of the game sucks, and it’s about time that got changed.

Who is everyone? That’s a pretty broad term to use. What “sucks” and why? This isn’t a helpful justification for your proposal.

 

Good:

• I’ve been talking to everyone, and we’ve all agreed this part of the game is frustrating to play. The enemies are overpowered, there’s not enough engagement, and I find myself struggling to continue.

A lot better. Still not defining who “everyone” is, and is probably inserting words into their mouths, but now we have something to go on. We can address specific elements and understand WHY you think this part of the game sucks, which is the biggest point you need to make.

 

Best:

• I’ve been talking to playtesters John, Mark, and Tom about this part of the game. I find this section of the game frustrating to play, and they agree with me. The enemies are overpowered, there’s not enough engagement with some of the gameplay elements and are tedious at best, and I find myself struggling to continue because I have to restart several times from bugs.

This is a GREAT way to state your reasoning. We have names of people and what they do, which carries a lot of weight. It just makes it sound so much more… important! It actually sounds like something that REALLY DOES need to be addressed now, and you even gave us the elements that specifically motivated you to make the proposal!

 

Details of Elements that you plan to add, change, or remove.

This is the meat and potatoes, and THE SINGLE MOST IMPORTANT PART. It’s pretty self explanatory what exactly this element of your proposal is trying to accomplish, so let’s focus on HOW you can make the most impact with this section.

First, details please! Don’t leave things open for assumption! This is especially bad when someone doesn’t agree with your idea; they will be inserting their own assumptions with a negative spin, which means now you have to fight on their turf before you can argue on your own merits. That isn’t easy.

That said, you need to carefully think through your idea. Abandon your preconceptions! If you have to make an assumption, so will someone else!

Avoid using uncertainties excessively. “Maybe”, “Could”, “Might”, etc. are uncertainties. You’re the one making the proposal, be confident in your idea. You can propose alternatives or ask for feedback, but be assertive!

Focus on the information people need to know, and keep the superfluous information minimal. Generally, it’s superfluous if you can take that information out or move it around, and it is making no impact on the point you are trying to make.

Examples:

Bad:

• I’m going to change the enemies so they are easier. They won’t die quickly enough! It’s a hard fight and I can’t seem to win! There will be more things to do, maybe some crafting, and an extra gun or two.

This is amateurish. Don’t submit such dribble. This is what you say during a discussion, but it doesn’t belong in a proposal. A proposal is a formal piece of writing. Plus, there’s redundant crap that doesn’t need to be in there.

 

Good:

• I’m going to change the enemies so they are easier. There will be some basic ammo crafting recipes to offset the ammo shortage, and two extra gun drops in a secret room behind the painting that will give more flexibility to the player to approach the upcoming fight.

I am hesitant to call this “good”, but it does provide enough info to get an idea of what direction you are taking things.

 

Best:

• I’m going to reduce the enemy health by 25%. There’s a hitpoint imbalance that I am addressing, which stems from the fact that I run out of ammo during the fight before I am able to find more. I also will add a simple crafting recipe to allow players to create more ammo from the scrap lying about, approximately three bolts for each piece of scrap, so that they don’t have to rely solely on finding ammo drops. That will add about 30 more bolts total in the level from crafting. Finally, as a bonus for exploring, there is a painting in the foyer that will have a corner torn and partially reveal something behind it. It will be a hidden room with two specialized weapons, one for sniping, and one for up close and personal brawling. Each will have advantages at different times in the fight, but these won’t be required to win.

This is a BEAUTIFUL piece of work. We know exactly what you plan to do, and why. We have lots of information regarding your idea, leaving little to be assumed. Plus, there’s little superfluous information, helping to keep the reader focused.

 

Concept Art

Concept art does a fantastic job of helping illustrate how you think your idea will look when implemented. Concept art is something that isn’t applicable for most things, but does a hell of a job of improving the quality of your proposal for things where it is applicable, IF DONE RIGHT. Stick to showcasing the main elements of your idea.

Concept art is basically a REQUIREMENT if you intend to change… you guessed it, ART ASSETS! Describing art in words is extremely tiring, both for reader and writer. If you intend to change a bunch of sprites, for example, include a couple of mock ups.

UI elements also benefit greatly from concept art, because it’s difficult to visualize complex elements. UI concept art doesn’t have to be a visualization of the final product though, just stick to approximations.

You don’t have to make concept art as good as your final product, as long as it gets the point across. There really aren’t many tips that can be given here about what concept art should consist of, that’s something you have to decide how much is enough. Ultimately, the more time you spend on concept art, the bigger the impact it will make!

Example:

Consider the following proposal change element to a UI:

• I want to change the configuration settings from just input boxes, to sliders and input boxes. When you get past three quarters of the scroll, it will accelerate greatly. The first three quarters will go from 0 to 10, the last will scale from 10 to 100. Example:

 

See what that does? Even in this simple example, it says SO MUCH when you make a piece of concept art! It didn’t even need to be something crazy professional; it still makes the point perfectly!

 

Development Plan

This is the part that appeals to the coders. It’s also the section that will greatly vary from idea to idea, and may not even be needed in some cases. Mainly, you want a development plan for BIG ideas. Things that do major additions and/or overhauls and require significant investment in time.

The biggest benefit to a development plan, is the ability to break a big idea down into small, digestible chunks. Generally, huge additions aren’t terribly difficult to implement, but huge CHANGES are. They are worlds apart. If you can break down your change into phases, this is much more likely to get through the approval process as things can be done in small steps, and to observe the effects as each step is done.

As a side note, the other useful and important thing about breaking things down into smaller chunks, is it makes it far less of a pain to eyeball your code. Short, small changes are much easier to digest and review. Big changes taking a dozen pages are a pain. Anything larger than that, and good luck getting ANYONE to dredge through that anytime soon.

You’ll have to decide how you want to lay out your development plan, and this can vary a lot too. Just keep it organized and intuitive to follow. The more detail you place into it, the better, as you can also use it as a sort of roadmap when you sit down to code your idea.

As an example, if our idea is to change weapons from hitscan to projectile based, that will probably take a lot of work. Think about all the time that has to be invested in something like that. Now, what if I told you the game engine you are using doesn’t support projectile weapons, so it’s something you have to spend time on as well? It gets daunting. Yet, if you break it down enough, it becomes manageable. Like so:

 

Phase I, Implement projectile physics in the engine

This phase will assess the feasibility of moving to projectile based weaponry physics.

• Select an appropriate physics library for use in the game based on expected operating parameters such as projectile speed, rate of fire, and complexity of firing solutions.

• Create test cases to measure performance

• Test multiplayer compatibility

• Compile results for review

 

Phase II, Refine and alter library to our specific circumstances.

Take data from Phase I, to make alterations with the following in mind:

• Changes to networking code to optimize projectile prediction on clients

• Alterations to the library as needed to better fit operating parameters. This will be further defined as development progresses.

• Determine what properties each weapon needs to have and test.

• Evaluate edge cases for re-design or stripping from the game

 

Phase III, Convert weaponry

• Polish implementation of weapon properties and functions regarding use of new projectile physics.

• Test and re-balance weaponry as necessary.

• Ship it!

 

Laying out a development plan like that shows you are also considering the technical aspects of implementing your idea. Complex ideas really should have a development plan!

 

 

Closing Thoughts

Ultimately, how you format and write your proposal is up to you. As mentioned, this is an optional process. You could take everything suggested in here, throw it out the window, and do everything from the ground up your own way. Just remember though, that the people reviewing your proposal will have certain expectations, so you really need to hit a homerun if you decide to deviate. Or, if you chose to forgo it altogether, that’s up to you. This is a suggested way for you to work with staff and the community to get a feel for your idea, to help you save time in the long run!

 

Good luck!

Edited May 18, 2017 by Anticept

[Anticept]

This is now official!

Remember:

THIS PROCESS IS ENTIRELY OPTIONAL

It is RECOMMENDED for large code changes, but still optional.

Edited May 18, 2017 by Anticept

[necaladun]

While not mandatory, this is a FANTASTIC time saver and useful way for us to assess things. A PR of the code can be hard for morons who don't know code (Read: Me) to understand.

Obviously don't need this for a super simple PR, but the more complex, the more this is helpful

Thanks again to Anticept for this

[Tayswift]

This is really cool and super detailed...maybe this should be pinned as a template? Or maybe there could be a separate subforum for code proposals or maybe the code suggestions forum could be appropriated?

Never mind, just realized this was pinned. Yay!

Edited May 18, 2017 by Tayswift