I am tasked with creating a document for current and (most importantly) new developers that is a general guidelines for the department. This is not a document on what the server name is for Test, but probably more of a company philosophy document.

Some of the items I currently have:

Coding Standards (naming, the basics)

Tiers - how to use each tier (like the preferred method for database access)

what would an example of "promoting code" look like?
–
chelmertzAug 11 '10 at 20:24

Just the procedures you go through to promote code ... like promote to dev, all developers test changes, promote to test, qa tests changes, promote to uat, business tests changes, etc.
–
MartinAug 13 '10 at 0:18

Aha, never heard of that term before, I've just been using the terms test, stage and deploy. Thanks!
–
chelmertzAug 13 '10 at 11:21

6 Answers
6

In the spirit of "We are not here to write code, we are here to make money for the company." I recommend a guidelines for time tracking, estimation, and core hours.

Also provide a brief outline of the various roles in your group and others, their responsibilities and the various communication points.

Do you perform code reviews, retrospectives or follow any management methodologies like waterfall, scrum, etc? You might wish to provide a briefing on how you facilitate these activities.

There's also the new developer orientation stuff like how to connect to the printer, what's an appropriate email signature, how to request vacation time, etc, but I don't think your document necessarily needs to speak to these points. But maybe so...

Spending resources on time-tracking, estimation (whatever that is) and core hours (ditto) does not in my experience make money for anyone. Point about code reviews is good though, so +1. And I would always value a tutorial on how to use the phone system, particularly, how to transfer a call.
–
anonAug 11 '10 at 18:33

@Neil Butterworth, Really? I guess it all depends on the shop. If developers are working for external customers who pay for services, guidelines on this activities are of extreme importance. It does depend on the nature of the business though and I certainly get your point.
–
Ben GriswoldAug 11 '10 at 19:00

My experience is that the customers haven't a clue how much time is spent, and neither have the programmers. All the figures are made up, so the less time spent on it the better.
–
anonAug 11 '10 at 19:03

Acceptable 3rd Party Licenses. We've had new hires work on a feature, then find out later on that they've included a GPL-licensed toolkit as part of it without realizing that was going to get them into hot water with our legal department.

Hmmm, if the saying "Perfection is reached not when there is nothing more to add, but when there is nothing more to take away" has a corollary, it must be something along the lines of "Reams and reams of not really necessary code cannot be high quality code by definition" :)
–
ninjaljAug 11 '10 at 17:30

Novice: "Master, is quality in the thing, or in the process that made the thing?" Master: "Foolish child - there is no thing!"
–
anonAug 11 '10 at 19:11

Perhaps associated with Source Control, keeping track of the licences for the libraries you may be using and keeping track of which code is yours (which you would be able to re-license later if you own the copyright).

Version control and repositories.

Associated with Coding standards, more than the name, the code formatting guidelines (easier to track changes with version control, otherwise things like change of spaces get in the way).

Documentation standards for source code. Remind them that one day, they may be doing maintenance on someone else's code, and remind them of the joys of maintaining well-documented APIs and logic.

Also, workstation setup guides. The last team I was one had documents explaining how to set up the workstation development environment for each application they maintained. It usually covered how to set up the projects in the IDE, how to connect to the servers/MQs/Database, and any other application-specific, non-intuitive quirks (and each app had its own peculiarities). For some applications, the set up was non-trivial (especially for newbies), and the process was its own document (apart from the others already mentioned).