Any Tips for Development Documentation?

A previous discussion that may be interesting: https://gamedev.net/forums/topic/710413-avoiding-pitfalls-when-implementing-a-partially-undefined-areas-of-the-design-document/

I think I find writing planning documentation helpful when:

1. I start working on large complex projects, or large features of an existing project, that can be broken down into smaller interdependent parts. It helps to clarify which sub-tasks depend on which other sub-tasks, and therefore which ones are worth tackling first. E.g., a 3D game needs a game loop, rendering, input handling, ray-casts, 3D assets; ray-casts need rays, bounding boxes, intersection tests; -- and so on.

2. I'm tackling a completely unfamiliar problem. Here, my notes help me nail down what it is that I even want from a hypothetical "solution." That in turn helps me figure out what my minimum viable (potentially hacky) solution looks like.

Since your struggle seems to be motivation more than anything else, though, I'd say keep a kind of journal of the work that you do every day.

I have a spreadsheet of the time I've spent being productive, with a couple of entries for each day every day. The entries from the spreadsheet are processed to produce charts visually showing me how I've spent my time. I've sometimes gone weeks, even months, without seeing any obvious results from the work or research I was doing. I think that's inevitable even for smaller projects. In those periods it really helped to see a number or line go up.

Basically, if persistence is your problem, change your win condition. Instead of needing to finish your project, your bar for accomplishment should be "I need to spend a minimum of X hours today doing something project related." It is a marathon, not a race.

lajohrawraef wrote:

I have dozens of projects that I would have to write the documentation for

No you don't. Your abandoned and failed projects, you don't have to do anything with them. You could unabandon and unfail one of 'em, and start working on it again... that's the only reason you'd even have to lift a finger.

You don't even have a documentation problem. Documentation is like for people to read later, to help things stay on track. That could be you later, or someone else.

You have a planning problem. Your planning sucks. You know it could theoretically help, but push come to shove when getting started, you just don't wanna do it and won't. So you dive right in, and actually get something done. Which is commendable! But then you hit this wall where you're confused and don't understand why you just did all this work. You throw more good work after bad, to no purpose, then give up in frustration when it obviously doesn't take you anywhere.

So what needs to change? What are you willing to change?

It's pretty clear to me, that you're going to have to start thinking about planning at some point. You don't like doing it up front; ok fine, lean into that. Your initial code spewing is commendable. But you're gonna have to plan sometime or you're gonna fail fail fail forever forever forever. The "rapid prototyping cycle / spiral" isn't all about go go go code code code. At some point you're going to need to take a deep breath, assess where you are, and think hard about whatever is tripping you up.

Are you lacking the analytical tools to think about what's really wrong with your design or development? Maybe that's your real issue, not planning. You can't plan something if you don't basically have a clue why you're doing anything.

Anyways I've never used anything other than a pen and a quad ruled engineering notebook to plan stuff. And I know all about overplanning. Things that never actually manage to turn into code. My point is that no fancy software or procedure will save you. You need to get to grips with what your personal sticking point is, and that requires self-honesty.