Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I've taken a software development role in an engineering company(all software developed is for internal use only). The company has about 60 individual projects from past developers. The problem is that all past developers are gone and no one knows why about half of the software was built, who uses it, or even what some of it does. We use SVN, but no past developers wrote comments or did any sort of documentation.

Assuming I figure all of this out, is there some program/system/method that could be used to keep track of all this information? The company is leaning toward Excel, I'm assuming there's something better. Would it just be better to write up documentation in a Word Doc and commit it to svn so it's right next to the code?

share|improve this question

closed as too broad by gnat, MichaelT, GlenH7, Dynamic, amon Apr 29 at 22:58

There are either too many possible answers, or good answers would be too long for this format. Please add details to narrow the answer set or to isolate an issue that can be answered in a few paragraphs.If this question can be reworded to fit the rules in the help center, please edit the question.

2  
How many developers are there maintaining those programs? A small team can live with a more or less informal solution, a bigger team may need something different. –  Doc Brown May 24 '13 at 13:53
    
@DocBrown There's only 2 of us, and I'm the one heading up the idea that we get it organized –  Brandon May 24 '13 at 15:15
1  
For 2 people, text files and Excel docs will most probably suffer your needs. Go with the suggestion of @DanPichelman. We are 4 devs here, inherited >200 programs and this still works fine. And I guess you meant "programs", not "projects" - a project is a task for a team - you don't look for a tool to keep track what 60 teams are doing (as your question title implies)? –  Doc Brown May 24 '13 at 15:36
2  
You should write another project for keeping track of the other projects. Be sure not to leave any notes or documentation so nobody knows why it was built, who uses it, or what it does. –  paul May 24 '13 at 15:39
1  
@Brandon I have to laugh at that, because if I didn't I'd start to cry. –  paul May 24 '13 at 18:40

8 Answers 8

up vote 13 down vote accepted

I use text files inside the project for that sort of thing. They're easy to maintain, easy to find and tough to misplace. Word or Excel would probably work just as well if you need to share but you'll need more discipline to write in some sort of log format so you can easily tell what changed when.

On a side note, I'd aggressively attempt to retire as many of those projects as possible - it's a lot easier to manage 20 projects than 60.

share|improve this answer
3  
+1 for the scaling down bit –  Onno May 24 '13 at 13:58

From what you're describing, it is inevitable that some work will have to be done to get a good idea of what you're dealing with here.

SVN is just the repository. It is meant to store your work in a way that enables you to make mistakes without that leading to big problems. It shouldn't be used to take care of project management!

If you can get some kind of funds for a cheap server running some software development project management/ALM software, it could help you out in terms of tracking development and user queries, all linked to your repo! I'm a big fan of using ALM software. It can help you communicate and plan your development in a way that makes the human link less of a dependency. If used properly, it can really help you structure your process. (It requires some discipline)

If you have the funds to run a windows server, go TFS. It seems a good fit to what you're describing, but costs more money compared to FOSS tools. On the other hand, it is a very nicely integrated set of tools, so it'll let you manage your projects in a nicely integrated environment with a shallow learning curve. (Assuming you don't want anything special. TFS is highly configurable, but a PITA to configure if you haven't worked with the techs involved before.)

FOSS alternatives that I like are: trac, redmine or chilliproject. Except for redmine, I've only used those as a user, so I can't really tell you how easy it is to set them up.

If management won't go any further than Excel, you're out of luck. It's down to common sense in that case. I'd suggest having some kind of overview sheet and one workbook per project with one page for bug tracking, one page for release planning, and one page for documenting releases. (Just made that up now, but seems a start if you're unable to get hold of proper tools to do your job)

In terms of who's using that softare? That's anyone's guess. The only way to tell is by polling potential users, unless they have connections over the network that you could scan for with the help of a/the network administrator. As far as telling what software does, you're going to have to analyse it if no docs are available and noone is able to provide you that info. The fast but inaccurate way would be to run it in some kind of sandbox and take a look. The slow but complete way would be to review the code. (Maybe reverse engineer it with the help of an UML tool with round trip capabilties for a quick overview of the structure)

As for as the no documentation part. This looks like a good time to point out the necessity of documentation. Docs have two sides: commenting code and creating overview/usage docs.

share|improve this answer
1  
FYI if you have 5 developers or less, TFS as a service is free and will be free forever. Takes about 5 min to set up. So OP doesn't need the funds :-) –  Kate Gregory May 30 '13 at 12:10
2  
TFS would also require Windows servers,plus sharepoint services, plus an AD domain. The cost of those isn't so great, but the overall cost, including training and admin, would be. Not that TFS is the best SCM around anyway, there are better FOSS tools that are easier to use and don't force you to put everything in Word or Excel. –  gbjbaanb May 30 '13 at 12:27
1  
Yes, TFS needs to run in a windows environment, but that's about it. Sharepoint comes with the product, and coupling it to an existing SharePoint service is optional. However, it is a system that is nicely integrated and easy to pick up without putting much work into getting it going. Most FOSS tools aren't integrated as well, which leads to more configuration and more maintenance. As far as ALM software with non-distributed SCM goes, TFS isn't half bad. –  Onno May 30 '13 at 13:04

Of course you will need to document as much as possible each project but you will also need a centralized "place" where you have your catalog of services/products, describing the "metadata" of the project as you pointed out: What department is using it? Who is responsible of maintaining it? What is it used for? What dependencies with other projects are there?

That "place" can be anything that works out for you and your company, like a document or an excel sheet. But of course you can use more "complex" tools or products like a wiki, a document management system, or specialized products on the matter.

I recommend you to take a look at ITIL, where they define what they call the ITIL Service Catalog: https://www.google.com/search?q=itil+service+catalog, just to have an idea.

share|improve this answer

As Dan points out, having a readme.txt in the project is cruical -- it doesn't need to be thick but it should cover enough to get a trained person building and debugging the code. The key things to cover are external configurations and dependencies and other landmine sort of things.

I would also advise using a project tracking tool with SCM integration. Personally I'm partial to redmine these days. If used properly they tend to be nice, easy, self-feeding documentation stores over time. I find our redmine is especially invaluable for occasions when one has to dive into a project that has been dormant for a long time as there are things one can learn from redmine that one can't learn from other project tools.

share|improve this answer

Instead of a simple spreadsheet or text file, I'd suggest something like TiddlyWiki. It's a simple wiki that runs entirely within a browser, so there's nothing to install or configure. Stick it in a public location and periodically back it up (just commit the file to a Subversion repo). It'll provide a bit of structure without (hopefully) being too limiting. If you need something more, Liferay offers an open-source portal-based "collaboration management" tool. I've used it on a couple of projects, but it's probably overkill for what you're trying to do.

share|improve this answer
    
I would also recommend a Wiki. Index page = list of links (initially all redlinks) to the 60 projects. Then you fill them in with whatever information you can gather. Over time, it will improve into something useful. –  Carson63000 May 24 '13 at 20:29

What you are referring to for managing a 'portfolio' of applications is either Project Portfolio Management (PPM) and/or Application Lifecycle Management (ALM). There are numerous tools from low-cost simple management to high-end management.

Do yourself and your organization a favor by NOT trying to put a band-aid on the problem with file based solutions. A few PPM tools I've implemented for clients include:

AtTask - Low tier, SaaS available, straightforward and limited configurability

Planview - High tier, SaaS available, ultimate configurability

Clarity - Mid tier, SaaS unknown, limited configurability

share|improve this answer

Redmine.

Create a project for each of your projects, hook each one up to the SVN section that contains the code and go from there. Each project will gain a bugtracker and a wiki and a way to track changes and information about each project as you determine what that info is. Additionally, you can see the code that comprises the projects and tie it to bugs or documents.

The 2nd bonus is you get a very good project management tool for free.

share|improve this answer

Redmine allows you to configure a hierarchy of projects, and each project has its own separate wiki. The wiki formatting is very simple, so you don't have to go crazy on it. Most wikis we create are just a single page, with links to outside references, a few paragraphs whining about poor code, and then some notes on important @todos.

It also supports source code integration, and there is syntax for linking directly to the code from the wiki, provided by a plugin.

share|improve this answer

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