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 programs 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?
8
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.
0
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.
4
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.
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.
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.
1
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
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.
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.