A little background: I work at a relatively small (<10 developers) tech company which basically produces a single product, which is constantly evolving and being added to. The product is an off-the-shelf client/server product, where we run the server and the clients are mobile apps running on a variety of platforms (Android, iOS, WinMo, etc.). The bulk of the specification and documentation is maintained in an internal Wiki.

Whenever we add a new feature or expand an existing one to the client apps, the process goes more or less like this:

  1. A spec. for the change is produced. Generally these specs are very low on detail, often just consisting of a few user stories: "As a user, I want to..."
  2. The feature is implemented on a single platform. Which platform often depends on which developer is most free at the time, as different developers specialise in different platforms.
  3. Once the feature is more or less completed on the lead platform, it gets ported to the other platforms.

Because the initial specification is so general, step 2 usually requires making a lot of the more detailed decisions - file formats, what to do when things go wrong, etc. Decisions are generally made after consultation with the project manager.

The problem we have is that there's no real procedure for making sure the decisions made in step 2 actually get documented. In an ideal world I guess responsibility might fall to the project manager, but since he's also a company director he frankly doesn't have the time!

My question is: Can anyone suggest a process (or processes) we could use to ensure these decisions get documented?

It's all very well to say "just update the wiki when decisions get made" but real-world considerations (time pressure, interruptions to deal with user support issues, etc.) often mean that it gets forgotten.

7 Answers 7


You really DO need to "just update the wiki when decisions get made." Interruptions and time pressure are NOT an excuse.

After all, you need to develop test cases, right? And you'll need to run these tests on each platform, right? Well, what should the tests be based on? That's right--those decisions you're not documenting. Document them, your testing will get better (and easier), your products will be assured of higher quality, and everyone is happy.

  • Not really the magic bullet I was hoping for, but without putting someone in charge of documentation (not really a viable option for our team) then "try harder" seems to be the only option... Commented Mar 2, 2012 at 17:04

The biggest problem with keeping documentation for code in a wiki is that a wiki's are nowhere near as flexible when it comes to version control.

That's one of the reasons I like to keep documentation as close to the code as possible, using a diff friendly documentation system like rst and storing the code in the project repository along with the code.

I distilled many of my thoughts on documentation into an answer to the question What are good ways to document scientific software? but they work as well for business code as for scientific code.

My third point about higher level documentation is the most directly relevant, but don't forget that once a project is complete, your unit tests probably document your requirements as implemented far better than your spec documents ever did, so you are probably better specifying future changes in terms of what you already have than what you originally wanted.

If you write your spec as a document in your project code repository, then if you branch your code for a new version, you also get a branch of the documentation. In your case, you would start a new branch of code development, update the spec, then update the code.

For the developer doing this everything would be in sync and no-one else would see the spec changes until they were ready to incorporate them.

Once the work had been done (or at least reached a deployable level) the changes in spec would be merged in with (ported) into the other projects along with the code that implements those spec changes.

The interesting thing is that the act of merging will also throw up merge conflicts if you have them, just as code would. That way you get to find out if two developers have changed the spec in ways which are mutually incompatible.

  • That doesn't really answer my question! I was interested in how to ensure the documentation was made/updated, not so much in the form the documentation takes. That said, +1 for some interesting info and I like the idea of committing spec updates along with the code that fulfils them. Commented Mar 2, 2012 at 17:01
  • @Baqueta I thought you were asking for a process to follow, not a way to get people to follow the process. *8') Glad you found it useful anyway.
    – Mark Booth
    Commented Mar 3, 2012 at 22:59
"The problem we have is that there's no real procedure for making sure the decisions made
 in step 2 actually get documented"

I think you've isolated the step in your process which you can improve. Without getting into changing your entire organizations structure, i think someone just has to be tasked with maintaining the spec as it evolves. I know it's obvious, but it will be the easiest way to achieve what you're up against. Introducing a new system will have some initial overhead, "Changing" the way you do things will probably ruffle more feathers than anything.

Hey, why not just assign it to the new guy (the FNG)!! LOL!!

good luck!


This has nothing to do with your special situation of "multiple platforms". Others have the same problem with just one platform. From a general point of view, I see two approaches to deal with this situation:

a) Do more up-front work in step 1. Try not to make just a functional spec, also try to specify non-functional requirements.

b) Avoid having to write avoidable documentation in step 2. Better teach your team how to write self-documenting code. Then there are less excuses like "we don't have the time for documentation". Of course, someone should update your Wiki also in step 2, but only for documenting high-level decisions. Those are most often only a small fraction of the things to be done at the code-level.

Here are two links to articles of Joel Spolsky which might be of interest for you:



  • Thanks for the input, I've not had chance to read those articles yet but they're on my reading list now. Also, I would say the 'multiple platforms' issue plays a role, since most of us only tend to work on one platform and the apps are structured differently on each platform (not a wise decision IMO!). Because of this, writing self-documenting code isn't necessarily that useful to the other devs. Commented Mar 2, 2012 at 16:36
  • @Baqueta: my suggestion was aiming of a better separation of high-level and low-level docs, so high-level-docs can be kept small, making it more painless to write it. By the way, does the port from one platform not involve taking source code 1, go through it line-by-line and function-by-function and transform it to platform 2?
    – Doc Brown
    Commented Mar 2, 2012 at 16:46

Use test driven development! Specifically, automate your system and integration tests when developing for the first platform. This is good practice even for one-off projects, but the benefits multiply when you are implementing the same functionality several times. I'm not sure what the tooling is like for iOS development, but I know there are tools you can use to drive UI testing in Android, for example.

Whether the tests are written up front (better) or added as you go (better than nothing), when you are finished that first version, you also have a complete, detailed and executable spec. What's more, it is guaranteed to be accurate -- something that is rarely true of paper specs. Use the same tests to drive your development for the other platforms (possibly with some tweeking) and you'll be sure you have uniformity of behavior even if you can't share a code base.

  • TDD (or at least unit testing) is definitely something I'm trying to nudge us in the direction of. I'm not aware of any practical way we could share the same tests across Java, C# and Objective-C though. Another obstacle to our using it is that much of the existing codebase which would require significant changes (dependency injection, proper MVC for UI components, etc) before unit tests would become practical. Commented Mar 2, 2012 at 16:46

Carry out a design proposal early in stage 2

Once the developer has worked out how they are going to do it they do a quick stand-up proposal to the rest of the team. This should be short, snappy and to the point, but basically get across the key points of

  1. What you're going to do
  2. What you decided not to do and why

A few supporting diagrams are really useful for the proposal and they can stored in your wiki. But don't feel the urge to always do them in a diagraming tool, a whiteboard scrawl that is then photographed is fine.

During the stand-up the other developers can quickly understand what is being done, see the thinking behind it and challenge it where appropriate before too much effort is expended.

As a result you have also now passed over the information to them - so what gets stored in the wiki only has to be an aide-mémoire rather than a definative full record. So simply store the diagrams along with a few notes to cover the key questions and points raised during the proposal stand-up.

If you're really keen (or if the developer thinks penning down the few notes required is too onerous) you could simply video the proposal and store that.

Its worth remembering that the key point #2 above is as important to record as the first - it reduces the chance of people expending effort in the future going "well clearly it should have been done this way ... oh hang on now I see why they didn't do that".

  • I like that this kills multiple birds with 1 stone. Definitely something I will suggest to our PM as something to try out. Commented Mar 2, 2012 at 16:39

Why are you documenting? It's not because your customers demand you are ISOxxxx compliant, it's not to put it on a feature list, it's because you think it saves you time in the long run. So saying you don't have time to do something that saves time only makes sense in a couple of situations:

  1. Doing it later will allow you to do things that make you grow enough to make it a smaller problem later, relative to your size.

  2. You are wasting time on purpose.

If you are growing so fast that #1 applies then stop reading this and get back to work.

If not, then the first time the documentation produces value is when you port to other platforms. Rather than communicate what you currently communicate informally anyway, write it down. Doing it later than that wastes some of the value it would have produced.

  • I get your point, but saving time in the short term often supercedes saving time in the long run. This has been the case for every company I've worked for! Commented Mar 2, 2012 at 16:53

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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