What do I need to do besides code?

Question

I'm a single-person operation for my small employer. I'm working on a couple of web applications that have grown to medium-size. We have backups going and everything is in version control with Subversion. I have comments in my code, but documentation outside of code is "spotty at best", and frequently things change.

What do I need to do to bring it to the next level, beyond a pile of ( version-controlled, well-commented ) code? What would you say is required to have a robust set of documentation outside of the codebase itself, where the project is at, and where it's going?

Ideally I would like some integrated system that would go from brainstorm, to requirements, to tracking bugs and features in svn check-in messages, to documentation. Would trac or redmine do something like this? I would like to show to my boss, "This is the prioritized list of features, this is where we are now, this is how long I spend on this feature, how long I spent on this bug" and I'd like to spend the minimum amount of time managing the projects :)

What about ERD and UML diagrams? Is a project incomplete without them?

Answer 1

i think you are on the right track. redmine, unfuddle or any other project management system is good for a project. this will give you an idea/road map of where the project should go. You can also switch to git instead of using subversion since it is more powerful(although if you're just one developer, i don't actually see any benefit)

most project management apps(i'll have to speak for redmine since we're also using that in our project) have a wiki/bug tracking/etc so you can go have a party with bug tickets + creating wiki pages for your timelines or such

Answer 2

Have a look at FogBugz (from the makers of Stack Overflow). It provides some of the features you're thinking of (I have a "priority list" project containing high-level features we want to add, and a separate project for bugs and features we're specifically working on).

It has a backlog feature that we use to prioritize everything we're working on as a company so that anyone can look and understand what will happen before what. If someone comes and says "I need you to squeeze this in", I can show them the backlog and ask "exactly what do you want me to move?".

Has a host of other great features I won't go into here.

FogBugz recently added source control integration as an add-on, but I have not used it so far.

It's free for small shops (1 or 2 people with accounts).

UML / ERD diagrams are only useful if they:

• Are used by someone
• Stay up-to-date

I find high level class diagrams useful for designing a new system on any project of any size. For larger projects, I find they only stay "fresh" if there's definite value associated with them staying fresh (diagrams for diagram's sake doesn't work well). On such larger projects, I try to get the team to a point where they can do significant code generation directly from UML (not just structure but also functionality). That creates value in having the diagrams stay up-to-date. In your case, you need to decide if there would be enough value in maintaining UML diagrams to make them worthwhile.

Answer 3

We use Assembla as it has built in Wiki, ticketing system and hosted SVN and Git repositories, as well as several other collaboration and project management tools.It allows checkins to be linked to tickets and wiki pages (so for example a checkin comment like "closes ticket #43" would actually close the ticket). It's reasonably priced for small organizations or single users.

A tool like this would be the next logical step in requirements traceability and project management.

Answer 4

I would look into setting up unit testing too. NUnit is a good one to look at if you're using any of the .Net languages.

Answer 5

In terms of documentation, I would say that you should definitely have a software architecture document and a build and deployment document. These documents are especially important since you are a single-person operation.

If you have time (and don't have it already) you may want to create an automated build process.

I would forgo creating detailed design documents based on the current application since things are changing and I'm not sure it would add much value. However, a high level software architecture is very useful in describing the application that you have built. Large architectural changes will probably not occur frequently so the document should not become outdated too quickly.

I would keep it simple and include things such as:

• core principles that have driven the architecture and design
• the software platform used
• major components (including third party software)
• how the application fits together (layers, etc.) with a simple diagram (or two)

If you have any application specific frameworks that you have developed then you may want to highlight the high level design and how to use it properly.

You should also document exactly how to build the software, how to package it, and how to deploy all the pieces (e.g. code, deployment scripts, database scripts, etc.) to the proper servers.

Answer 6

We have a very similar set-up, a small web-shop with 2 developers. Previously we had about 6 developers. Since then, I've changed the whole set-up not because I just felt like it but I actually needed to do something. Each s/w product we managed was reliant on the discipline of each team member. However there was too much manual fiddling about on multiple servers, no automation and no control. Now there is only myself and a colleague, I have the authority to do something about it without waiting for everyone to follow.

Some things I think have helped:

1) Introduced version control (we didn't use it before!)

2) Create a continuous build system using NANT, CruiseControl.NET

3) Auto sync of db schema using RedGate SQLCompare

4) Documenting of internal bugs using BugTracker.NET (in addition to our ticketing system which is not so good for quick documenting of internal bugs & better for customers)

5) Document of fixed bugs in PDF s/w release forms

6) Just started using Selenium UI tests

Next steps I would like to take on board are:

6) Better documenting, design using UML diagrams

7) Use code generation tools like T4?

8) Use better UI framework like Coolite/ExtJs/Telerik...

9) Start writing testable code which can be tested with NUnit. Since we are using ASP.NET webforms, this is not easy but achievable. Our current architecture makes unit testing difficult so I need to investigate how to go about this.

Maybe some of these pointers might help.