Documentation (best practices discussion. No code)

[Sauron]

7 hours ago, fpo said:

Do you think the planning & debating should mostly (90%) occur before coding/prototyping for a clear direction or do you think that the planning/debating should occur during programming to constantly shift the project to stay on top of trends & whatnot?

I think a lack of flexibility during the project could be problematic.

[Unimportant]

14 hours ago, fpo said:

how important is it to have planned out the project before writing code if the project is intended to be large scale? 

Very, there's often more planning then code-writing going on. More precisely, the objects(classes) and their layout/relation to each other should be worked out before you start coding. You can't just get at it and start writing a bunch of classes haphazardly and only then consider how everything is going to fit together.

Yes, classes should be lightly coupled, and for some classes that can be done. But in a large project there will be some tight coupling going on whether you like it or not and you better had planned for it.

 

14 hours ago, fpo said:

How in depth should that be? Elevator pitch level or the project planned & now we just need the code to fill in the spaces.

The actual pitch level isn't of much importance. Rather the fact that there is a elevator, it's pitch can be changed, what elements are affected by changes in the elevator, where does the elevator fit in, who's responsible for it, etc...

15 hours ago, fpo said:

If you were brought into a project that had no planning nor documentation, what are your chances of staying? 

Planning is a team effort over here, so when you're brought into a new project there's not yet been any planning - The team does the planning first before commencing.

I've never been brought into a existing project where everyone was working without a plan - I don't think such projects would be long-lived anyway.

[HunterAP]

Personally, I generally write documentation for code that's either too big for me to remember everything (even with lots of comments), or if this code is going to be used by someone else ( at which point I just assume that the end user is a complete idiot so I make the docs really specific and in-depth).

 

I mostly separate the docs into this format:

1. Introduction / Purpose / Goal
2. Requirements
3. Installation
4. How To Use
5. Issues / Issue Tracking
6. Changelog

And usually having multiple subsections inside #4 depending on the complexity of the program.

Also using Doxygen + GitHub pages really helps in keeping the formatting nice and clean, but still detailed.