What constitutes a development environment, and how do you document it?

Question

What items go into a software shop's development environment, how do you document it, and what processes do you follow to make changes?

I thinking about this from the standpoint where I want to make it easier to bring new hires up to speed quickly by having all this on a checklist we follow when setting them up, and then while I'm at it making it easier for the new hires or existing team members to bring new powerful toolkits and ideas into the environment without disrupting things.

I want to keep this platform agnostic, so even though I'm currently at a microsoft shop where Visual Studio would be assumed I'll go ahead and list compiler/IDE as one of the items:

Here are some ideas for part 1:

[edit]: I'm keeping this updated based on the better suggestions.

• Source Control access
• Issue/Bug/Project tracker
• System Documention, or references to find the system documentation in source control or in a wiki, including:
  • build document/environment covered by this question
  • design documents / technical notes
  • Coding Style guidelines
  • Deploy for review/testing/QA/staging/production procedures
  • Licensing details for your tools and your product
  • Team Calendar, including the project schedule(s), deadlines, vacation time, and support/on-call schedule (if required)
• compiler/IDE
• compiler/IDE extensions (things like source control plugins or visual studio add-ins)
• 3rd party SDKs/toolkits
• Database connection and tools
• Testing Frameworks
• Internal libraries
• communication tools (chat, wiki, etc)
• Static analysis tools (FxCop, FlawFinder, etc)
• Virtual machines (holding dev environment or for testing)
• Specialized editors (modeling, xml, etc)
• Other tools

What else goes in this list, and how do you document it and vet changes?

Answer 1

For versionning: all is in the Source Control. And, after the table of content, a table with all version with a brief description of the change. This way, manager can see the evolution without needing to connect in the source control to know what has changed.

I have a master document (project plan) that refer to the requirement document, test document, etc.

For changes, I have a Request of change system. This way, all change need to be approved by the client and is clearly identified who request it, who did the evaluation (dev side) and who approved on the client side. This way, if the schedule change, we have proof that the client changed thing in the path of developpement.

Answer 2

Something I have found useful in the past is a build document, this would include a checklist at the beginning and full instructions for each item, how to install it what options to use etc.

Answer 3

That's a good list to start with.

You might like to add test frameworks, e.g. CUnit, CPPUnit to your shopping list there.

And also peer review procedures, e.g. a peer review template and library of previously seen "gotchas".

Ah, and maybe add a static analysis tool, e.g. FlawFinder. But remember, you still need a careful inspection of the code, "A fool with a tool is still a fool!"

BTW The book Practical Development Environments (Amazon link) is an excellent resource for this.

HTH.

cheers,

Rob

Answer 4

Kill the generic "Other tools" section and list them out. As for me (and I'm a .NET developer) my other tools include:

• IE & Firefox (as well as any other browser I need to support)
• The developer extensions for IE & Firefox
• WATIR & Ruby (for testing web applications)
• SQL Server Management Studio (or whatever DB tool)
• Word Processor (ex: Word)
• Project Management tool (ex: MS Project)
• Diagramming tool (ex: Visio)

As for documenting it, use a word document or an excel spreadsheet in a Source Control repository labeled as Development Environment and make sure you list the ORDER that these applications should be installed on the box (for example, you need to install VS2008 prior to Office 2007).

Answer 5

If you use modeling tools, those need to be documented as well, especially if you're a model-driven architecture shop. ;)

Answer 6

Wiki.

Saving common procedures in a wiki has helped me immensely, and I've only been doing it for two weeks. This helps new people help themselves. And, if they find a deviation or something confusing, they can update the wiki themselves.

We have pages for how to build x, how to test x, how to package x, how to test x, etc. This is a great place for things like configuration tips, registry keys, gotchas, etc.

We are currently using Redmine for task management, bug tracking, wiki, etc. It's been very nice to us (and it's free).

Answer 7

I'd include a section on how to challenge/change any or all of those items. I'd also include a lot more documentation on the processes and guidelines, as they are at least as important as the software environment.

For example:

• How to get a different external library to be accepted as a valid external dependency
• How to get a new version of an existing library accepted as a valid external dependency
• How are IDE-Upgrades handled. Do you always use the latest version? If not, what's the process of upgrading to the latest version?
• What's the process of fixing a bug (what of tiny one-line-fixes? Do they need a bug report?)
• Commit comment guidelines
• How are version numbers of software components defined. Who decides when to go to the next version?
• Are alternate versions of the standard tools allowed, if the developer wishes? If so, what are the minimum requirements for these tools (common file format support, for example).
• What QA tools do you use? What do you use for load testing? Stress testing?

Answer 8

Why don't you create an installer for developers? It's pretty easy and the benefits are incredible.

If you're interested in more details, I wrote an article about just this on my blog entitled: How To Quickly Setup a Software Development Environment

Answer 9

I find that a development system image is invaluable. That way, everyone is testing on the same setup, rather than each person setting up their own environment that doesn't quite match everyone else's. Naturally, that works best if you're in a VM environment.

Answer 10

License keys and the like are as important as the installation of the tools themselves. The best way to deal with it is first imagine what if it was ten years from now. The tools are generally straight forward to document but sometimes the licensing isn't. Make sure that is included in your documentation.

Also make sure you include setup information on the computer itself. Like additional hardward, settings on the hardware, drivers, etc. I know you have a test environment in a Virtual Machine but you need the external environment where you code and build to be correct as well. Especially if you want to do dynamic debugging.

Answer 11

I've worked on several teams that used a wiki (such as MediaWiki, Confluence, or TikiWiki--to name just a few) for documenting their development environment. A wiki works well because development pipelines tend to change over time, and it takes something of a living document (something with built-in revision control that everyone on the team has read and write access to) to properly capture much of it, depending on the size of your team/project.

Your documentation should include write-ups of the various processes vital to the project's development, including the following:

• A step-by-step guide for creating a working build of your project
• How to run the unit tests / smoke tests / test harness, as well as add to them
• How to search bug reports, submit a bug report, and close off fixed bugs
• Getting project changes committed (process for sign-off on work, getting work into repository)
• How to create, test, package up, and push out a release version of the project

The wiki can be a good place for project team members to document ideas and suggestions for improving these processes.

I've also found that, as a project member, I can use the wiki to help gauge the health of a team. If the wiki is neglected, it's probable that team communication and morale are hurting too. Any team where vital processes like the ones in the list above are hoarded by managers and distributed on a "need-to-know" basis is not one that I would want to work for.

Answer 12

Another thought would be to have a weekly, "Patterns & Practices," meeting where someone introduces something new to the team. It could be something as simple as a couple of tricks within the IDE or it could be giving an overview of some new framework that a couple of developers think is worth the others knowing or it could be where some cross-training happens so that it isn't one guy that knows all about how XYZ is done here.

Would it make sense to try to have an initial month mapped out for new hires? For example, could there be time devoted to getting them to hit the ground running with some new feature or bug fixing in the current project in the first week with a couple of other milestones mapped out so that new guys contribute something fairly early on.

Answer 13

Here is the list:

• Source Control
  • Access Procedures
  • Directory Layout
  • Branch philosophy
  • Main Line
  • SQL Changes
  • Build Tools
• Continuous Integration
• List of all servers
• Foreach Server
  • Operating System
  • IIS Version
  • .Net Frameworks Installed
  • Third party applications / components installed
  • IIS Configuration
  • Firewall rules
  • DNS Entries
  • Applications installed
  • MSMQ setup
  • Machine.config settings
  • ODBC settings
  • OLEDB settings
  • Registry Settings
• Foreach Application
  • Type of application
    • Web Site
    • Web Service
    • Windows Service
    • Scheduled Task
    • Click Once
  • For Web / Windows Service
    • List of calling applications
    • URL to call
    • Ports opened
    • Firewall rules
    • DNS entries
  • Related Web / Windows Services called
    • URLs for services
    • Firewall rules required
    • DNS Entries required
  • Databases Access
    • Permissions / Roles used
    • Stored procedures called
    • Linked Servers used
  • Filesystem access
    • Logging
    • Documentation
    • Uploads
    • Downloads
  • Last know good deployment to Production
  • Source Control Location
  • Tool for searching source control
  • Tool to control changes going into production
  • Tool for tracking bugs
  • Tool for documenting environment configuration
  • Tool for capturing knowledge (Wiki)
  • Policies and procedures
  • Coding Conventions
  • Checkin Process
  • Getting QA Approval
  • Submitting move to production
  • Fixing Bugs
  • Fixing Build Breaks
  • Unit Testing
  • Code Documentation

This is all I could think of at the moment I probably have a lot more to add. I am in the process of implementing this for our organization. Hope this helps.