Our team is distributed in space and time, so we have no ability to discuss the architecture of the code in real time. How can we discuss it via documentation: write code interfaces/ comment/ modify, track history of the code architecture? Are there some specific tools for this? What are the best way: class diagrams, code interfaces, something different? We are using c# and VS2010

  • 6
    Our team is distributed in space and time. Do we finally have time machine? I have a lot of things to fix using it... – Snowbear Jun 22 '11 at 9:32
  • @Raynos: the question is about how to discuss with a distributed team. – Hun1Ahpu Jun 22 '11 at 10:45
  • your right, I didn't notice the emphasis on what tools are available. I can't recommend any tool over another. – Raynos Jun 22 '11 at 10:47
  • Our team is distributed in space and time. Can I join your team? I'm so sick of deadlines pushing terrible code into production. With you guys I'd never have a deadline again! – Xeoncross Jun 22 '11 at 21:05

10 Answers 10


What is the best way to discuss/plan/negotiate about code architecture remotely?

There are a lot of techniques, depending on your team. I would highly recommend using version control and then standardizing on a word processor and diagram editor (down to the version), depending on team preferences. This will ensure that everyone can view and edit the diagrams and documents produced.

A major problem with many version control systems is that binary files can not be diffed or merged. You must be aware of this, as a lot of what is produced by word processors and diagram editors are binary files. Make sure that you don't stomp on other people's work.

How can we discuss it via documentation: write code interfaces/ comment/ modify, track history of the code architecture?

When discussing an architecture, it's important to realize different types of views of the system. Different stakeholders require different views of the system in order to perform analysis, detailed design, and implementation. An example of a set of views would be the 4+1 Architectural View Model which uses a series of various UML diagrams to show various aspects of the system. I focused on the 4+1 Model and choosing the appropriate UML diagrams for each view in the software architecture course I took.

If you are using various UML diagrams, you need to identify which ones you want. The 4+1 Model does suggest various diagrams for each view, but there are 14 types of diagrams in UML 2.2, and the diagrams that you will find useful will vary depending on the project.

As far as code interfaces, don't get too detailed in the architecture phase. There might be certain interfaces expected by the client that you know about (especially if you are creating an API for consumption), and it's fine to work with those. But don't get caught up in anything not clearly specified by your requirements when it comes to specific details at the class level - that can come later on in design.

Any version control that you are using can keep track of changes. As I mentioned before, you'll probably be working with a number of binary files, so you'll have to be extra careful and use detailed change notes since diffing files becomes more difficult.

We are using c# and VS2010

Architecture, and even high-level design decisions, should be independent of the implementation language and tools that you are using. Don't let the tools you are using guide you until you get into detailed design decisions, when you choose which language features will best help you realize your architecture and high-level design decisions previously made.

| improve this answer | |
  • 1
    I don't know what you said, but +1 for all the text and acronyms. – Xeoncross Jun 22 '11 at 21:06

Google Docs or documentation files checked into source control along with email will do fine for most things. Being able to version documentation is nice, but Google Docs is real time so you do not have to wait around for check-ins. This method may not be enough for everyone, but the simplest method is always the first to look at.

| improve this answer | |

Have a look at Campfire, it seems pretty suited to what you're after. It does text, files, code, images chat. It saves a history so you can check back on what was discussed before. There's a free trial so give it a shot...

If you need more features I believe there are plugins that might be useful.

(I have no connection with 37signals)

| improve this answer | |

This might seem like a given for a lot of users of this site, but it's fairly new to my toolset so I'm still excited about it. One of my favorite things about version-control tools (I've used CVS, Subversion, and Mercurial for different projects) is the fact that source files are not the only things you can put in them. Any format of file can be in your repo, which means you can have design and documentation files in whatever format you choose. In addition to traditional version-control like the items named, Dropbox is a great tool for having a shared collection of files across multiple devices.

Tools like these, coupled with one of the many remote desktop/remote presentation tools available (I like Teamviewer (windows) and NoMachine (Linux)), make it fairly easy to pull off the desired effect.

| improve this answer | |

In addition to the tools there is training and a common vocabulary.

Invest in architecture patterns training.

Then when some one says "we will use the singleton pattern", "we will use the repository pattern" or "we will use the facade pattern". Everyone knows what they are talking about.

| improve this answer | |

I use Google Docs for all of my documentation. It allows my fellow co-workers to see the latest changes in real time, it keeps a revision history, supports access rights management (so your silly boss can't mess around with the files ;) and you can leave comments. Just make a folder and share it with your co-workers. You can also insert images in your documents, so it's quite complete. Then when you're ready to move on and code it, you have the documents accessible from anywhere, so you can also work from anywhere, but I would say using a bug tracker is essential in a distributed project---I personally like Redmine.

| improve this answer | |

Though we are not that scattered in space and time, but we sometimes use "design videos" instead of design documents to pass on design/architecture/documentation related knowledge. I think this might be handy in your case.

| improve this answer | |
  • This sounds interesting... anything you can share? – Michael Jun 23 '11 at 16:57
  • Share? I'm not sure we are on the same page here :D It's usually internal stuff, pretty much code/domain specific. Not the typical technical training videos, if I understood you right – Shady M. Najib Jun 23 '11 at 17:10
  • I did not think it was a generic training video. I was just curious what your design videos ended up looking like, what kind of information they conveyed and how you did it. Is it a screen cast walking through code? Teammembers talking around a whiteboard? A recorded presentation? Something else entirely? What are the most important things to include in a video architecture description? I assumed you would not be able to share but I thought I'd ask anyway. – Michael Jun 24 '11 at 12:55
  • Nop.. sorry, it's pretty common here that I take for granted that you know how we do it.. Anyway, you got it right, mostly it's a a code walk-through screen cast. Sometimes if the architecture is really complex we might add a diagram (the same as the architecture document) with extra (video) explanation of it, sometimes even relating the code walk-through to the architecture if it's not really an obvious relation – Shady M. Najib Jun 24 '11 at 13:51

Since you're using VS2010 already, can you upgrade to 2010 Ultimate with TFS?
You can compare the features here We've used this to a good extent with teams spread across the globe and working in different time zones. There is a cost involved though. I'm not sure how it compares to some of the other solutions mentioned here.

| improve this answer | |

If you get VS2010 Ultimate, you can generate dependency graphs from code to help you visualize relationships, namespaces, classes, members, and so on. You can also create layer diagrams, sequence diagrams, and class diagrams from code and also other UML diagrams.

For more info, see this MSDN Library topic: Modeling Your Application

| improve this answer | |

Let us not forget the lowly mailing list, and IRC.

I would also say that you could use graphviz, since the .dot files are plain text, and you could generate them with code... Plain text is good for version control systems.

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.