Duplicate maintenance - code and documentation [closed]

Question

This may not be the best title - I would appreciate it if someone would come up with a better one after reading my problem. Also, I want to say up front that I am largely self-taught on the Internet, so there may be many tools that I am not aware of.

I am maintaining software implementing the Flow-Based Programming (FBP) concept in both Java and C#. For each of these, I have code on:

• my website
• SourceForge File Release System (zip files or jar files)
• SourceForge SVN

In addition, I have version references and (sometimes partial) descriptions on:

• my web site (HTML)
• my wiki
• Javadoc

There is also a drawing tool, also on my website and SourceForge, that has to know about the latest version of the Java version of the FBP code.

Everything is cross-linked pretty thoroughly, but sometimes I miss a reference! A few days ago, I realized that I hadn't updated SourceForge News for my project in a long time, so I had to hustle and do that :-)

I realize that some of these vehicles are probably redundant, but generally, I do not know who is watching what.

So my question is whether there is a way to reduce all this overhead, E.g. an HTML "imbed" function would be nice, so I can at least store the latest version number in one place. I can probably simplify the Java cross-references, but inter-language would be even nicer, but unlikely, I guess.

Any ideas would be welcome.

Answer 1

It seems to me that you want to update and maintain your documentation as part of your build/deploy process e.g.

1. build
2. unit test etc
3. compile documentation
4. deploy builds
5. deploy compiled documentation

otherwise you're always going to be chasing your tail. Obviously the documentation deployment will require different solutions on where it's going (e.g. copied to your website, FTPed elsewhere etc.)

I'm not sure there's a panacea for all of this. I maintain version numbers in properties files/config files, and do appropriate search/replaces. Code documentation wherever possible goes in the code itself, and then that's preprocessed in my build (step 3 above).

Have you seen/used doxygen ? That will handle your multi-language requirements, and is well established for building/maintaining documentation.

Answer 2

It sounds like you need to automate your build/publishing process. I read this article on O'Reilly awhile back - it seems you both have rather similar situations? His solution makes heavy use of Python, but at the very least, it might give you a few ideas.