Add a 'guide to the development process' doc

[I-am-Erk]

trafficstars

Summary

Infrastructure "Adds a guide to the development process"

Purpose of change

As the project continues to eternally grow, it's a constant quality improvement issue to make sure that the new contributor onboarding process is as friendly as we can reasonably make it, while also having to manage a pretty enormous community full of people with various degrees of socially awkward nerdiness ranging from "high" to "unbelievably extreme", both on the developer and the prospective contributor side

After interviewing some experienced contributors, new contributors, and prospective contributors who had expressed concerns about what the contribution process looks like from the outside, I compiled a list of common feelings people had that they wished could have been addressed sooner in their experience.

Describe the solution

I've added a document that I hope addresses a lot of these common misunderstandings and concerns by outright stating the lessons that contributors say they had to work out the hard way. Universally, the people I spoke to felt that overall the development process works well, once they understood it, and the community was welcoming and friendly. However, there were many areas where they didn't feel this until they came to understand the process better, and this is what I hope to address.

This is a first draft. I've cut out thousands of words already, but I could always use a new eye for wording, brevity, and structure.

I'm not completely sure yet how to make this more visible, that's the next step once we're satisfied with the wording

Describe alternatives you've considered

I considered breaking this up into a few smaller documents but I don't think it would help.

Testing

n/a

Additional context

The project history stuff is not at all necessary, I just think it's neat.

[Drew4484]

Might help to add something along the linee of "When X and Z got added, we didn't deliberately remove or leave out Y, feel free to add it." Anvils might be a good example, the update added some options and changes a few existing items but the PR was not called 'Add more innawoods anvils'.

[I-am-Erk]

Might help to add something along the linee of "When X and Z got added, we didn't deliberately remove or leave out Y, feel free to add it." Anvils might be a good example, the update added some options and changes a few existing items but the PR was not called 'Add more innawoods anvils'.

Yes, good one. Thanks

[I-am-Erk]

Oh, I also should add a bit about who "owns" a character or a faction or whatever

[NetSysFire]

I have not read everything yet but:

1. This reads like a verbose blog post again. Please work on writing more concise things.
2. CONTRIBUTING.md exists and you should probably mention this document there.
3. Keep a look out for other documentation potentially already describing this. I looked around and found CONTRIBUTING.md that must be accounted for but I have a vague feeling there are more files like that laying around.

Edit: Feeling was right! https://github.com/CleverRaven/Cataclysm-DDA/wiki/Guide-to-adding-new-content-to-CDDA-for-first-time-contributors - and theres probably more.

[I-am-Erk]

It's a good idea to link it in both contributing.md and in the guide to new contributors, but the content is very different from either of those.

It probably is more verbose than it needs to be and I'm open to suggestions, but the prose format is intentional. This isn't code documentation, it's a guide.

[TheSaddestGoomba]

A lot of this is more fitting of an FAQ format. That may curb some of the need for brevity if users are expected to treat it as a directory, jumping to the sections relevant to them, rather than a guide meant to be read start to end.

[I-am-Erk]

A lot of this is more fitting of an FAQ format. That may curb some of the need for brevity if users are expected to treat it as a directory, jumping to the sections relevant to them, rather than a guide meant to be read start to end.

That's reasonable, it's not really intended to be read cover to cover. I will add a TOC before it's out of draft. I've also already cut >400 words just out of the first few paragraphs, so it's not going to be nearly this long by the end. I tend to start long and edit down.

[I-am-Erk]

I've cut the main body down to 6k words now and can probably get a fair bit more out after i take a break. I've moved some of the interesting fluff commentary to footnotes, which IMO helps a lot but I'd be interested in a second opinion there.

EDIT: It's down to 5400 words in the main body now, and I think that's as far as I can easily get it on my own. It's a lot more manageable though. It also has a table of contents, and I've reworded a number of the topic headings to be more clearly a FAQ.

[zachary-kaelan]

I read the whole thing and I love it, I think it looks great.

Only thing missing is I need to know why Kevin placed that landmine that killed my character.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions. Please do not bump or comment on this issue unless you are actively working on it. Stale issues, and stale issues that are closed are still considered.

[Night-Pryanik]

I read the whole document and I think it's fine. I guess it's ready to be merged as is and then updated/modified if needed. Unless @I-am-Erk de-drafts it by himself, I plan to do it and merge it in a few days.

[I-am-Erk]

Thanks NP