What would be items for Developer's Guide for a workplace? [closed]

Clash Royale CLAN TAG#URR8PPP

.everyoneloves__top-leaderboard:empty,.everyoneloves__mid-leaderboard:empty margin-bottom:0;

up vote
0
down vote

favorite

1

I am the team lead (not manager) for a new group of developers, all recent hires, and we are hiring more.

I'd like to write up a kind of guideline for us as a team, and for new developers coming in to the team. I have a basic outline of things I want to cover:

• Guiding Principles (of the document)


• Culture


• Environment


• Projects


• Code

I don't want it to be too extensive or take more than an hour to go through but to give new and current developers a head start on the particular environment for development that we have here. It will go through the choices made for TDD, Unit Testing, Code Style, Source Control, Branching Workflow, presenting ideas to the team, code reviews, etc.

If you were a new developer coming on to a new or existing team what are the types of information you would want to quickly reference so that your code fits in with the current culture and you can get up to speed quickly?

I've already added to the document that it is a living thing that we can update over time. Its essentially a bulleted list of decisions that have been made in one form or another, so that it can be quickly updated with new bullets or changing existing ones.

developer documentation

share|improve this question

edited Sep 17 '14 at 15:14

asked Sep 16 '14 at 18:18

Jeff Martin

1657

closed as off-topic by IDrinkandIKnowThings, gnat, yochannah, Elysian Fields♦ Sep 16 '14 at 23:28

• This question does not appear to be about the workplace within the scope defined in the help center.

If this question can be reworded to fit the rules in the help center, please edit the question.

• 
  
  
  

  
  

  
  
  
  
  
  

  
  Probably it is hard to find as the information on this would be very much company confidential
  – HLGEM
  Sep 16 '14 at 18:36
  

  
  
  
  


• 
  
  
  

  
  

  
  
  
  
  
  

  
  If you don't plan on it taking more than an hour to go through, do you think it is worth your time to write a guide book, or explain these things in a team meeting/several team meetings. You can use a half hour for each section during each meeting if you needed to split it up. This allows them to write down important pieces and you could always create/share a power point with them also. If your Guide Book was going to be more detailed and used as a reference, I would agree with you on writing one, but if it is light I am not sure if it's necessary.
  – Mark C.
  Sep 16 '14 at 18:46
  

  
  
  
  


• 
  
  
  

  
  3
  

  
  
  
  
  
  

  
  This question appears to be off-topic because it is not about navigating the workplace as described in the help center
  – IDrinkandIKnowThings
  Sep 16 '14 at 18:47
  

  
  
  
  


• 
  
  
  

  
  1
  

  
  
  
  
  
  

  
  This probably isn't sufficient for an answer, but you should use a wiki for this. It's one of the few things that I think wikis are really good for, but that sort of technology can easily help you link to things as well as allow it to be fluid over time.
  – Telastyn
  Sep 16 '14 at 19:08
  

  
  
  
  


• 
  
  
  

  
  

  
  
  
  
  
  

  
  Yes, a wiki is definitely useful for questions that recur over and over again. But more than anything else, the best thing is to cultivate an environment where people are willing to help others by patiently answering questions, providing guidance and mentorship. I find that "guidelines" documents end up being about as interesting as a legal document and easily ignored. But perhaps more perniciously, such document encourage an attitude of "RTFM" among the authors while dismissing the importance of interactivity and engagement.
  – teego1967
  Sep 16 '14 at 22:39
  

  
  
  
  

 | 
show 3 more comments

up vote
0
down vote

favorite

1

I am the team lead (not manager) for a new group of developers, all recent hires, and we are hiring more.

I'd like to write up a kind of guideline for us as a team, and for new developers coming in to the team. I have a basic outline of things I want to cover:

• Guiding Principles (of the document)


• Culture


• Environment


• Projects


• Code

I don't want it to be too extensive or take more than an hour to go through but to give new and current developers a head start on the particular environment for development that we have here. It will go through the choices made for TDD, Unit Testing, Code Style, Source Control, Branching Workflow, presenting ideas to the team, code reviews, etc.

If you were a new developer coming on to a new or existing team what are the types of information you would want to quickly reference so that your code fits in with the current culture and you can get up to speed quickly?

I've already added to the document that it is a living thing that we can update over time. Its essentially a bulleted list of decisions that have been made in one form or another, so that it can be quickly updated with new bullets or changing existing ones.

developer documentation

share|improve this question

edited Sep 17 '14 at 15:14

asked Sep 16 '14 at 18:18

Jeff Martin

1657

closed as off-topic by IDrinkandIKnowThings, gnat, yochannah, Elysian Fields♦ Sep 16 '14 at 23:28

• This question does not appear to be about the workplace within the scope defined in the help center.

If this question can be reworded to fit the rules in the help center, please edit the question.

• 
  
  
  

  
  

  
  
  
  
  
  

  
  Probably it is hard to find as the information on this would be very much company confidential
  – HLGEM
  Sep 16 '14 at 18:36
  

  
  
  
  


• 
  
  
  

  
  

  
  
  
  
  
  

  
  If you don't plan on it taking more than an hour to go through, do you think it is worth your time to write a guide book, or explain these things in a team meeting/several team meetings. You can use a half hour for each section during each meeting if you needed to split it up. This allows them to write down important pieces and you could always create/share a power point with them also. If your Guide Book was going to be more detailed and used as a reference, I would agree with you on writing one, but if it is light I am not sure if it's necessary.
  – Mark C.
  Sep 16 '14 at 18:46
  

  
  
  
  


• 
  
  
  

  
  3
  

  
  
  
  
  
  

  
  This question appears to be off-topic because it is not about navigating the workplace as described in the help center
  – IDrinkandIKnowThings
  Sep 16 '14 at 18:47
  

  
  
  
  


• 
  
  
  

  
  1
  

  
  
  
  
  
  

  
  This probably isn't sufficient for an answer, but you should use a wiki for this. It's one of the few things that I think wikis are really good for, but that sort of technology can easily help you link to things as well as allow it to be fluid over time.
  – Telastyn
  Sep 16 '14 at 19:08
  

  
  
  
  


• 
  
  
  

  
  

  
  
  
  
  
  

  
  Yes, a wiki is definitely useful for questions that recur over and over again. But more than anything else, the best thing is to cultivate an environment where people are willing to help others by patiently answering questions, providing guidance and mentorship. I find that "guidelines" documents end up being about as interesting as a legal document and easily ignored. But perhaps more perniciously, such document encourage an attitude of "RTFM" among the authors while dismissing the importance of interactivity and engagement.
  – teego1967
  Sep 16 '14 at 22:39
  

  
  
  
  

 | 
show 3 more comments

up vote
0
down vote

favorite

1

up vote
0
down vote

favorite

1

1

I am the team lead (not manager) for a new group of developers, all recent hires, and we are hiring more.

I'd like to write up a kind of guideline for us as a team, and for new developers coming in to the team. I have a basic outline of things I want to cover:

• Guiding Principles (of the document)


• Culture


• Environment


• Projects


• Code

I don't want it to be too extensive or take more than an hour to go through but to give new and current developers a head start on the particular environment for development that we have here. It will go through the choices made for TDD, Unit Testing, Code Style, Source Control, Branching Workflow, presenting ideas to the team, code reviews, etc.

If you were a new developer coming on to a new or existing team what are the types of information you would want to quickly reference so that your code fits in with the current culture and you can get up to speed quickly?

I've already added to the document that it is a living thing that we can update over time. Its essentially a bulleted list of decisions that have been made in one form or another, so that it can be quickly updated with new bullets or changing existing ones.

developer documentation

share|improve this question

edited Sep 17 '14 at 15:14

asked Sep 16 '14 at 18:18

Jeff Martin

1657

I am the team lead (not manager) for a new group of developers, all recent hires, and we are hiring more.

I'd like to write up a kind of guideline for us as a team, and for new developers coming in to the team. I have a basic outline of things I want to cover:

• Guiding Principles (of the document)


• Culture


• Environment


• Projects


• Code

I don't want it to be too extensive or take more than an hour to go through but to give new and current developers a head start on the particular environment for development that we have here. It will go through the choices made for TDD, Unit Testing, Code Style, Source Control, Branching Workflow, presenting ideas to the team, code reviews, etc.

If you were a new developer coming on to a new or existing team what are the types of information you would want to quickly reference so that your code fits in with the current culture and you can get up to speed quickly?

I've already added to the document that it is a living thing that we can update over time. Its essentially a bulleted list of decisions that have been made in one form or another, so that it can be quickly updated with new bullets or changing existing ones.

developer documentation

share|improve this question

edited Sep 17 '14 at 15:14

asked Sep 16 '14 at 18:18

Jeff Martin

1657

share|improve this question

share|improve this question

edited Sep 17 '14 at 15:14

edited Sep 17 '14 at 15:14

edited Sep 17 '14 at 15:14

asked Sep 16 '14 at 18:18

Jeff Martin

1657

asked Sep 16 '14 at 18:18

Jeff Martin

1657

asked Sep 16 '14 at 18:18

Jeff Martin

1657

1657

closed as off-topic by IDrinkandIKnowThings, gnat, yochannah, Elysian Fields♦ Sep 16 '14 at 23:28

• This question does not appear to be about the workplace within the scope defined in the help center.

If this question can be reworded to fit the rules in the help center, please edit the question.

closed as off-topic by IDrinkandIKnowThings, gnat, yochannah, Elysian Fields♦ Sep 16 '14 at 23:28

• This question does not appear to be about the workplace within the scope defined in the help center.

If this question can be reworded to fit the rules in the help center, please edit the question.

• 
  
  
  

  
  

  
  
  
  
  
  

  
  Probably it is hard to find as the information on this would be very much company confidential
  – HLGEM
  Sep 16 '14 at 18:36
  

  
  
  
  


• 
  
  
  

  
  

  
  
  
  
  
  

  
  If you don't plan on it taking more than an hour to go through, do you think it is worth your time to write a guide book, or explain these things in a team meeting/several team meetings. You can use a half hour for each section during each meeting if you needed to split it up. This allows them to write down important pieces and you could always create/share a power point with them also. If your Guide Book was going to be more detailed and used as a reference, I would agree with you on writing one, but if it is light I am not sure if it's necessary.
  – Mark C.
  Sep 16 '14 at 18:46
  

  
  
  
  


• 
  
  
  

  
  3
  

  
  
  
  
  
  

  
  This question appears to be off-topic because it is not about navigating the workplace as described in the help center
  – IDrinkandIKnowThings
  Sep 16 '14 at 18:47
  

  
  
  
  


• 
  
  
  

  
  1
  

  
  
  
  
  
  

  
  This probably isn't sufficient for an answer, but you should use a wiki for this. It's one of the few things that I think wikis are really good for, but that sort of technology can easily help you link to things as well as allow it to be fluid over time.
  – Telastyn
  Sep 16 '14 at 19:08
  

  
  
  
  


• 
  
  
  

  
  

  
  
  
  
  
  

  
  Yes, a wiki is definitely useful for questions that recur over and over again. But more than anything else, the best thing is to cultivate an environment where people are willing to help others by patiently answering questions, providing guidance and mentorship. I find that "guidelines" documents end up being about as interesting as a legal document and easily ignored. But perhaps more perniciously, such document encourage an attitude of "RTFM" among the authors while dismissing the importance of interactivity and engagement.
  – teego1967
  Sep 16 '14 at 22:39
  

  
  
  
  

 | 
show 3 more comments

• 
  
  
  

  
  

  
  
  
  
  
  

  
  Probably it is hard to find as the information on this would be very much company confidential
  – HLGEM
  Sep 16 '14 at 18:36
  

  
  
  
  


• 
  
  
  

  
  

  
  
  
  
  
  

  
  If you don't plan on it taking more than an hour to go through, do you think it is worth your time to write a guide book, or explain these things in a team meeting/several team meetings. You can use a half hour for each section during each meeting if you needed to split it up. This allows them to write down important pieces and you could always create/share a power point with them also. If your Guide Book was going to be more detailed and used as a reference, I would agree with you on writing one, but if it is light I am not sure if it's necessary.
  – Mark C.
  Sep 16 '14 at 18:46
  

  
  
  
  


• 
  
  
  

  
  3
  

  
  
  
  
  
  

  
  This question appears to be off-topic because it is not about navigating the workplace as described in the help center
  – IDrinkandIKnowThings
  Sep 16 '14 at 18:47
  

  
  
  
  


• 
  
  
  

  
  1
  

  
  
  
  
  
  

  
  This probably isn't sufficient for an answer, but you should use a wiki for this. It's one of the few things that I think wikis are really good for, but that sort of technology can easily help you link to things as well as allow it to be fluid over time.
  – Telastyn
  Sep 16 '14 at 19:08
  

  
  
  
  


• 
  
  
  

  
  

  
  
  
  
  
  

  
  Yes, a wiki is definitely useful for questions that recur over and over again. But more than anything else, the best thing is to cultivate an environment where people are willing to help others by patiently answering questions, providing guidance and mentorship. I find that "guidelines" documents end up being about as interesting as a legal document and easily ignored. But perhaps more perniciously, such document encourage an attitude of "RTFM" among the authors while dismissing the importance of interactivity and engagement.
  – teego1967
  Sep 16 '14 at 22:39
  

  
  
  
  

Probably it is hard to find as the information on this would be very much company confidential
– HLGEM
Sep 16 '14 at 18:36

Probably it is hard to find as the information on this would be very much company confidential
– HLGEM
Sep 16 '14 at 18:36

If you don't plan on it taking more than an hour to go through, do you think it is worth your time to write a guide book, or explain these things in a team meeting/several team meetings. You can use a half hour for each section during each meeting if you needed to split it up. This allows them to write down important pieces and you could always create/share a power point with them also. If your Guide Book was going to be more detailed and used as a reference, I would agree with you on writing one, but if it is light I am not sure if it's necessary.
– Mark C.
Sep 16 '14 at 18:46

If you don't plan on it taking more than an hour to go through, do you think it is worth your time to write a guide book, or explain these things in a team meeting/several team meetings. You can use a half hour for each section during each meeting if you needed to split it up. This allows them to write down important pieces and you could always create/share a power point with them also. If your Guide Book was going to be more detailed and used as a reference, I would agree with you on writing one, but if it is light I am not sure if it's necessary.
– Mark C.
Sep 16 '14 at 18:46

3

3

This question appears to be off-topic because it is not about navigating the workplace as described in the help center
– IDrinkandIKnowThings
Sep 16 '14 at 18:47

This question appears to be off-topic because it is not about navigating the workplace as described in the help center
– IDrinkandIKnowThings
Sep 16 '14 at 18:47

1

1

This probably isn't sufficient for an answer, but you should use a wiki for this. It's one of the few things that I think wikis are really good for, but that sort of technology can easily help you link to things as well as allow it to be fluid over time.
– Telastyn
Sep 16 '14 at 19:08

This probably isn't sufficient for an answer, but you should use a wiki for this. It's one of the few things that I think wikis are really good for, but that sort of technology can easily help you link to things as well as allow it to be fluid over time.
– Telastyn
Sep 16 '14 at 19:08

Yes, a wiki is definitely useful for questions that recur over and over again. But more than anything else, the best thing is to cultivate an environment where people are willing to help others by patiently answering questions, providing guidance and mentorship. I find that "guidelines" documents end up being about as interesting as a legal document and easily ignored. But perhaps more perniciously, such document encourage an attitude of "RTFM" among the authors while dismissing the importance of interactivity and engagement.
– teego1967
Sep 16 '14 at 22:39

Yes, a wiki is definitely useful for questions that recur over and over again. But more than anything else, the best thing is to cultivate an environment where people are willing to help others by patiently answering questions, providing guidance and mentorship. I find that "guidelines" documents end up being about as interesting as a legal document and easily ignored. But perhaps more perniciously, such document encourage an attitude of "RTFM" among the authors while dismissing the importance of interactivity and engagement.
– teego1967
Sep 16 '14 at 22:39

 | 
show 3 more comments

3 Answers
3

active

oldest

votes

up vote
1
down vote



accepted

I've written up a number of "guidelines" for dev teams in the past, generally speaking it's something you really should do, and is also wildly impractical.

Why should we do it?

Simple, you can't afford to have everyone doing the same thing in a different way on your team as it gets cludgy and hard to maintain. You also want to help the new guys avoid the sort of mistakes it takes only a minute to address.

It's also good even in more experienced teams to come to a consensus on how to do something and stick to it for sake of maintainability and readability purposes.

What's impractical about this?

A guide itself is hard to use. Someone will read it, and forget it quickly as generally speaking we retain less than 20% of what we read. In addition telling people to always "check the guide" does you no good if the guide only covers a small amount. Of coarse making the guide cover almost everything is simply impractical.

Even if you were to establish the guide that covers everything it would need to change as technology and your company grows and changes.

Limit the guide

For the "new hire" guide you want to keep it strictly to things unique about your company. How do you test? Where does your code live? What's the proper chain of command? How do requests work their way to the devs? What is the completion process? What documentation is expected of them? etc.

Use other tools

There are countless things you'll be tempted to add to your guide that you simply shouldn't. Coding standards, best practices, etc. These are best left to tools that are more functional than a guide. For those of us in C# setting up resharper to handle your coding standards takes the burden off the individual. You can also setup a wiki to document your internal systems are processes.

Unwarranted Advice

My advice as a new team lead is you CAN NOT force your way of coding on others. We devs just don't take being told how to do things well and you'll probably just get heavy resistance. The key is getting your team invested into standards. Set the standards as a team. When you need to set a standard (for example how you'll publish projects) you should sit with the team and work out as a team what makes the most sense, then that is your standard (documented in your tool of choice) until such time that the standard needs to be updated due to changes in the way the company does business or technology.

share|improve this answer

answered Sep 16 '14 at 19:30

RualStorge

9,5372231

suggest improvements | 

up vote
1
down vote

I can't share the document as it contains company specific and confidential information.

But ours contains

Configuration section 
 Database servers (dev, QA, Staging, Prod) 
 Source Control locations 
 Build Server 
 Web Servers 
 URLS 
 FTP site 
 SQL Server Agent Jobs and scheduled times 
 SSIS import and Export packages 
Dev software requirements (which versions of what they must have) 
Key people on the project and their responsibilities and contact info. 

This could all be broken out by client or project or both.

share|improve this answer

answered Sep 16 '14 at 18:44

HLGEM

133k25226489

suggest improvements | 

up vote
0
down vote

These types of things tend to be fluid in nature. What I mean by that is your team may have a starting point but as time moves on key decisions will be reversed.

A very simple example might be a coding convention where the curly braces are on their own lines. Later on, enough team members demand that be changed and poof a new direction is taken. It might even be just time changes like everyone being required to show up at a 7:00AM daily stand up meeting... only to hire someone that drops their kids off at school and can't make it to the office before 8:30... These might seem minor, but each change means that your document has to be updated or it quickly becomes unusable.

Looking at your list:

Guiding Principles is akin to a short mission statement and shouldn't take more than 3 or 4 sentences. Create a plaque and post it on the wall if you feel the need.

Culture / Environment beyond expected work hours is something that people learn through immersion, and is constantly in flux as new hires are integrated into the team.

Projects / Code choices should be either readily apparent or quickly justifiable - as in it shouldn't take more than 5 minutes to discuss it. If it does, then there is plenty of room for potential change. Further, if you're thinking about creating a 50 page document then you're doing it wrong. Stick to the standards employed by the producer of your tools (MS/Oracle/etc). If you have to say something then you might just ponder Codeless Code case #94.

Now, if you are just documenting where things are located, again, that's a one pager.. or better yet, make it a standard welcome email.

share|improve this answer

edited Sep 16 '14 at 19:00

answered Sep 16 '14 at 18:47

NotMe

20.9k55695

suggest improvements | 

3 Answers
3

active

oldest

votes

3 Answers
3

active

oldest

votes

active

oldest

votes

active

oldest

votes

up vote
1
down vote



accepted

I've written up a number of "guidelines" for dev teams in the past, generally speaking it's something you really should do, and is also wildly impractical.

Why should we do it?

Simple, you can't afford to have everyone doing the same thing in a different way on your team as it gets cludgy and hard to maintain. You also want to help the new guys avoid the sort of mistakes it takes only a minute to address.

It's also good even in more experienced teams to come to a consensus on how to do something and stick to it for sake of maintainability and readability purposes.

What's impractical about this?

A guide itself is hard to use. Someone will read it, and forget it quickly as generally speaking we retain less than 20% of what we read. In addition telling people to always "check the guide" does you no good if the guide only covers a small amount. Of coarse making the guide cover almost everything is simply impractical.

Even if you were to establish the guide that covers everything it would need to change as technology and your company grows and changes.

Limit the guide

For the "new hire" guide you want to keep it strictly to things unique about your company. How do you test? Where does your code live? What's the proper chain of command? How do requests work their way to the devs? What is the completion process? What documentation is expected of them? etc.

Use other tools

There are countless things you'll be tempted to add to your guide that you simply shouldn't. Coding standards, best practices, etc. These are best left to tools that are more functional than a guide. For those of us in C# setting up resharper to handle your coding standards takes the burden off the individual. You can also setup a wiki to document your internal systems are processes.

Unwarranted Advice

My advice as a new team lead is you CAN NOT force your way of coding on others. We devs just don't take being told how to do things well and you'll probably just get heavy resistance. The key is getting your team invested into standards. Set the standards as a team. When you need to set a standard (for example how you'll publish projects) you should sit with the team and work out as a team what makes the most sense, then that is your standard (documented in your tool of choice) until such time that the standard needs to be updated due to changes in the way the company does business or technology.

share|improve this answer

answered Sep 16 '14 at 19:30

RualStorge

9,5372231

suggest improvements | 

up vote
1
down vote



accepted

I've written up a number of "guidelines" for dev teams in the past, generally speaking it's something you really should do, and is also wildly impractical.

Why should we do it?

Simple, you can't afford to have everyone doing the same thing in a different way on your team as it gets cludgy and hard to maintain. You also want to help the new guys avoid the sort of mistakes it takes only a minute to address.

It's also good even in more experienced teams to come to a consensus on how to do something and stick to it for sake of maintainability and readability purposes.

What's impractical about this?

A guide itself is hard to use. Someone will read it, and forget it quickly as generally speaking we retain less than 20% of what we read. In addition telling people to always "check the guide" does you no good if the guide only covers a small amount. Of coarse making the guide cover almost everything is simply impractical.

Even if you were to establish the guide that covers everything it would need to change as technology and your company grows and changes.

Limit the guide

For the "new hire" guide you want to keep it strictly to things unique about your company. How do you test? Where does your code live? What's the proper chain of command? How do requests work their way to the devs? What is the completion process? What documentation is expected of them? etc.

Use other tools

There are countless things you'll be tempted to add to your guide that you simply shouldn't. Coding standards, best practices, etc. These are best left to tools that are more functional than a guide. For those of us in C# setting up resharper to handle your coding standards takes the burden off the individual. You can also setup a wiki to document your internal systems are processes.

Unwarranted Advice

My advice as a new team lead is you CAN NOT force your way of coding on others. We devs just don't take being told how to do things well and you'll probably just get heavy resistance. The key is getting your team invested into standards. Set the standards as a team. When you need to set a standard (for example how you'll publish projects) you should sit with the team and work out as a team what makes the most sense, then that is your standard (documented in your tool of choice) until such time that the standard needs to be updated due to changes in the way the company does business or technology.

share|improve this answer

answered Sep 16 '14 at 19:30

RualStorge

9,5372231

suggest improvements | 

up vote
1
down vote



accepted

up vote
1
down vote



accepted

I've written up a number of "guidelines" for dev teams in the past, generally speaking it's something you really should do, and is also wildly impractical.

Why should we do it?

Simple, you can't afford to have everyone doing the same thing in a different way on your team as it gets cludgy and hard to maintain. You also want to help the new guys avoid the sort of mistakes it takes only a minute to address.

It's also good even in more experienced teams to come to a consensus on how to do something and stick to it for sake of maintainability and readability purposes.

What's impractical about this?

A guide itself is hard to use. Someone will read it, and forget it quickly as generally speaking we retain less than 20% of what we read. In addition telling people to always "check the guide" does you no good if the guide only covers a small amount. Of coarse making the guide cover almost everything is simply impractical.

Even if you were to establish the guide that covers everything it would need to change as technology and your company grows and changes.

Limit the guide

For the "new hire" guide you want to keep it strictly to things unique about your company. How do you test? Where does your code live? What's the proper chain of command? How do requests work their way to the devs? What is the completion process? What documentation is expected of them? etc.

Use other tools

There are countless things you'll be tempted to add to your guide that you simply shouldn't. Coding standards, best practices, etc. These are best left to tools that are more functional than a guide. For those of us in C# setting up resharper to handle your coding standards takes the burden off the individual. You can also setup a wiki to document your internal systems are processes.

Unwarranted Advice

My advice as a new team lead is you CAN NOT force your way of coding on others. We devs just don't take being told how to do things well and you'll probably just get heavy resistance. The key is getting your team invested into standards. Set the standards as a team. When you need to set a standard (for example how you'll publish projects) you should sit with the team and work out as a team what makes the most sense, then that is your standard (documented in your tool of choice) until such time that the standard needs to be updated due to changes in the way the company does business or technology.

share|improve this answer

answered Sep 16 '14 at 19:30

RualStorge

9,5372231

I've written up a number of "guidelines" for dev teams in the past, generally speaking it's something you really should do, and is also wildly impractical.

Why should we do it?

Simple, you can't afford to have everyone doing the same thing in a different way on your team as it gets cludgy and hard to maintain. You also want to help the new guys avoid the sort of mistakes it takes only a minute to address.

It's also good even in more experienced teams to come to a consensus on how to do something and stick to it for sake of maintainability and readability purposes.

What's impractical about this?

A guide itself is hard to use. Someone will read it, and forget it quickly as generally speaking we retain less than 20% of what we read. In addition telling people to always "check the guide" does you no good if the guide only covers a small amount. Of coarse making the guide cover almost everything is simply impractical.

Even if you were to establish the guide that covers everything it would need to change as technology and your company grows and changes.

Limit the guide

For the "new hire" guide you want to keep it strictly to things unique about your company. How do you test? Where does your code live? What's the proper chain of command? How do requests work their way to the devs? What is the completion process? What documentation is expected of them? etc.

Use other tools

There are countless things you'll be tempted to add to your guide that you simply shouldn't. Coding standards, best practices, etc. These are best left to tools that are more functional than a guide. For those of us in C# setting up resharper to handle your coding standards takes the burden off the individual. You can also setup a wiki to document your internal systems are processes.

Unwarranted Advice

My advice as a new team lead is you CAN NOT force your way of coding on others. We devs just don't take being told how to do things well and you'll probably just get heavy resistance. The key is getting your team invested into standards. Set the standards as a team. When you need to set a standard (for example how you'll publish projects) you should sit with the team and work out as a team what makes the most sense, then that is your standard (documented in your tool of choice) until such time that the standard needs to be updated due to changes in the way the company does business or technology.

share|improve this answer

answered Sep 16 '14 at 19:30

RualStorge

9,5372231

share|improve this answer

share|improve this answer

answered Sep 16 '14 at 19:30

RualStorge

9,5372231

answered Sep 16 '14 at 19:30

RualStorge

9,5372231

answered Sep 16 '14 at 19:30

RualStorge

9,5372231

9,5372231

suggest improvements | 

suggest improvements | 

up vote
1
down vote

I can't share the document as it contains company specific and confidential information.

But ours contains

Configuration section 
 Database servers (dev, QA, Staging, Prod) 
 Source Control locations 
 Build Server 
 Web Servers 
 URLS 
 FTP site 
 SQL Server Agent Jobs and scheduled times 
 SSIS import and Export packages 
Dev software requirements (which versions of what they must have) 
Key people on the project and their responsibilities and contact info. 

This could all be broken out by client or project or both.

share|improve this answer

answered Sep 16 '14 at 18:44

HLGEM

133k25226489

suggest improvements | 

up vote
1
down vote

I can't share the document as it contains company specific and confidential information.

But ours contains

Configuration section 
 Database servers (dev, QA, Staging, Prod) 
 Source Control locations 
 Build Server 
 Web Servers 
 URLS 
 FTP site 
 SQL Server Agent Jobs and scheduled times 
 SSIS import and Export packages 
Dev software requirements (which versions of what they must have) 
Key people on the project and their responsibilities and contact info. 

This could all be broken out by client or project or both.

share|improve this answer

answered Sep 16 '14 at 18:44

HLGEM

133k25226489

suggest improvements | 

up vote
1
down vote

up vote
1
down vote

I can't share the document as it contains company specific and confidential information.

But ours contains

Configuration section 
 Database servers (dev, QA, Staging, Prod) 
 Source Control locations 
 Build Server 
 Web Servers 
 URLS 
 FTP site 
 SQL Server Agent Jobs and scheduled times 
 SSIS import and Export packages 
Dev software requirements (which versions of what they must have) 
Key people on the project and their responsibilities and contact info. 

This could all be broken out by client or project or both.

share|improve this answer

answered Sep 16 '14 at 18:44

HLGEM

133k25226489

I can't share the document as it contains company specific and confidential information.

But ours contains

Configuration section 
 Database servers (dev, QA, Staging, Prod) 
 Source Control locations 
 Build Server 
 Web Servers 
 URLS 
 FTP site 
 SQL Server Agent Jobs and scheduled times 
 SSIS import and Export packages 
Dev software requirements (which versions of what they must have) 
Key people on the project and their responsibilities and contact info. 

This could all be broken out by client or project or both.

share|improve this answer

answered Sep 16 '14 at 18:44

HLGEM

133k25226489

share|improve this answer

share|improve this answer

answered Sep 16 '14 at 18:44

HLGEM

133k25226489

answered Sep 16 '14 at 18:44

HLGEM

133k25226489

answered Sep 16 '14 at 18:44

HLGEM

133k25226489

133k25226489

suggest improvements | 

suggest improvements | 

up vote
0
down vote

These types of things tend to be fluid in nature. What I mean by that is your team may have a starting point but as time moves on key decisions will be reversed.

A very simple example might be a coding convention where the curly braces are on their own lines. Later on, enough team members demand that be changed and poof a new direction is taken. It might even be just time changes like everyone being required to show up at a 7:00AM daily stand up meeting... only to hire someone that drops their kids off at school and can't make it to the office before 8:30... These might seem minor, but each change means that your document has to be updated or it quickly becomes unusable.

Looking at your list:

Guiding Principles is akin to a short mission statement and shouldn't take more than 3 or 4 sentences. Create a plaque and post it on the wall if you feel the need.

Culture / Environment beyond expected work hours is something that people learn through immersion, and is constantly in flux as new hires are integrated into the team.

Projects / Code choices should be either readily apparent or quickly justifiable - as in it shouldn't take more than 5 minutes to discuss it. If it does, then there is plenty of room for potential change. Further, if you're thinking about creating a 50 page document then you're doing it wrong. Stick to the standards employed by the producer of your tools (MS/Oracle/etc). If you have to say something then you might just ponder Codeless Code case #94.

Now, if you are just documenting where things are located, again, that's a one pager.. or better yet, make it a standard welcome email.

share|improve this answer

edited Sep 16 '14 at 19:00

answered Sep 16 '14 at 18:47

NotMe

20.9k55695

suggest improvements | 

up vote
0
down vote

These types of things tend to be fluid in nature. What I mean by that is your team may have a starting point but as time moves on key decisions will be reversed.

A very simple example might be a coding convention where the curly braces are on their own lines. Later on, enough team members demand that be changed and poof a new direction is taken. It might even be just time changes like everyone being required to show up at a 7:00AM daily stand up meeting... only to hire someone that drops their kids off at school and can't make it to the office before 8:30... These might seem minor, but each change means that your document has to be updated or it quickly becomes unusable.

Looking at your list:

Guiding Principles is akin to a short mission statement and shouldn't take more than 3 or 4 sentences. Create a plaque and post it on the wall if you feel the need.

Culture / Environment beyond expected work hours is something that people learn through immersion, and is constantly in flux as new hires are integrated into the team.

Projects / Code choices should be either readily apparent or quickly justifiable - as in it shouldn't take more than 5 minutes to discuss it. If it does, then there is plenty of room for potential change. Further, if you're thinking about creating a 50 page document then you're doing it wrong. Stick to the standards employed by the producer of your tools (MS/Oracle/etc). If you have to say something then you might just ponder Codeless Code case #94.

Now, if you are just documenting where things are located, again, that's a one pager.. or better yet, make it a standard welcome email.

share|improve this answer

edited Sep 16 '14 at 19:00

answered Sep 16 '14 at 18:47

NotMe

20.9k55695

suggest improvements | 

up vote
0
down vote

up vote
0
down vote

These types of things tend to be fluid in nature. What I mean by that is your team may have a starting point but as time moves on key decisions will be reversed.

A very simple example might be a coding convention where the curly braces are on their own lines. Later on, enough team members demand that be changed and poof a new direction is taken. It might even be just time changes like everyone being required to show up at a 7:00AM daily stand up meeting... only to hire someone that drops their kids off at school and can't make it to the office before 8:30... These might seem minor, but each change means that your document has to be updated or it quickly becomes unusable.

Looking at your list:

Guiding Principles is akin to a short mission statement and shouldn't take more than 3 or 4 sentences. Create a plaque and post it on the wall if you feel the need.

Culture / Environment beyond expected work hours is something that people learn through immersion, and is constantly in flux as new hires are integrated into the team.

Projects / Code choices should be either readily apparent or quickly justifiable - as in it shouldn't take more than 5 minutes to discuss it. If it does, then there is plenty of room for potential change. Further, if you're thinking about creating a 50 page document then you're doing it wrong. Stick to the standards employed by the producer of your tools (MS/Oracle/etc). If you have to say something then you might just ponder Codeless Code case #94.

Now, if you are just documenting where things are located, again, that's a one pager.. or better yet, make it a standard welcome email.

share|improve this answer

edited Sep 16 '14 at 19:00

answered Sep 16 '14 at 18:47

NotMe

20.9k55695

These types of things tend to be fluid in nature. What I mean by that is your team may have a starting point but as time moves on key decisions will be reversed.

A very simple example might be a coding convention where the curly braces are on their own lines. Later on, enough team members demand that be changed and poof a new direction is taken. It might even be just time changes like everyone being required to show up at a 7:00AM daily stand up meeting... only to hire someone that drops their kids off at school and can't make it to the office before 8:30... These might seem minor, but each change means that your document has to be updated or it quickly becomes unusable.

Looking at your list:

Guiding Principles is akin to a short mission statement and shouldn't take more than 3 or 4 sentences. Create a plaque and post it on the wall if you feel the need.

Culture / Environment beyond expected work hours is something that people learn through immersion, and is constantly in flux as new hires are integrated into the team.

Projects / Code choices should be either readily apparent or quickly justifiable - as in it shouldn't take more than 5 minutes to discuss it. If it does, then there is plenty of room for potential change. Further, if you're thinking about creating a 50 page document then you're doing it wrong. Stick to the standards employed by the producer of your tools (MS/Oracle/etc). If you have to say something then you might just ponder Codeless Code case #94.

Now, if you are just documenting where things are located, again, that's a one pager.. or better yet, make it a standard welcome email.

share|improve this answer

edited Sep 16 '14 at 19:00

answered Sep 16 '14 at 18:47

NotMe

20.9k55695

share|improve this answer

share|improve this answer

edited Sep 16 '14 at 19:00

edited Sep 16 '14 at 19:00

edited Sep 16 '14 at 19:00

answered Sep 16 '14 at 18:47

NotMe

20.9k55695

answered Sep 16 '14 at 18:47

NotMe

20.9k55695

answered Sep 16 '14 at 18:47

NotMe

20.9k55695

20.9k55695

suggest improvements | 

suggest improvements |