Django on speaking terms (with itself)

 
 
 
 

DocTool, my take on systems documentation

 

When I started out doing web applications I used plain CGI. One of the sites I built was a kind of proof-of-concept of some theory I had about how to structure application documentation in all its aspects, as well as how to interrelate the various documents involved.

Basically it consisted of five sections: the project homepage, specs from the user point of view (including rfc's), spec from a functional design point of view, technical specs, and program documentation. These would each be subdivided into subcategories.

For each description it would be possible to define a relation with a description of a certain other category, implicitely defining the relation in the other direction. This was all done using XML as a data storage medium with each description stored in a separate document. So the relations had to be stored explicitely, and because I developed that part later, they were stored in a separate XML file.

Navigation was done using a selector containing a list of projects, and a css pulldown menu to select actions on documents and move from section to section. Obviously this wouldn't function in Internet Explorer, so I had to add some Javascript to make it work there too.

 

ProbReg, reviving stuff I found useful

 

Around the same time - or maybe earlier or perhaps later - when I was doing GUIs, I rebuilt a tool I had built at work (on the mainframe, in a procedural language) for keeping track of problems and their solutions.

It was somebody else's design and I improved just a little on it, using a wxPython Notebook interface.

It contained a list of problems, a details page, and three pages each containing a large text field describing problem, solution and possible follow-up respectively. My addition was a page with events, inspired by a claims-handling application we built at work that contained a similar mechanism: a short description automatically added for every action taken with the possibility to manually add on to them as a form of notes.

 

Great!? Rewrite!

 

For some reason I had to teach myself Django. After a while, I rewrote most of my CGI web apps using it, among others the aforementioned DocTool. I had to convert the storage system to SQL, which wasn't that bad, and was able to solve a few problems I hadn't gotten around to yet - like finishing some sections I hadn't implemented before. Since most of the stuff was pretty similar I used a lot of introspection - sacrificing some readability for the sake of not repeating myself too often. Also I put the technical categories together and introduced another one: testing.

The interface was changed as well: instead of the pull down menu I built a three-selector system: the first one being similar to the first menu option, and the second one being similar to selecting a menu; after selecting a category you'd get the third selector which would make it possible to select a section.

For some other reason I got the idea to rewrite the GUI app for problem registration as a web app. For the sake of collaboration I added some user adminstration to it, so that it could be registered who was working on stuff and making it possible to transfer the work to another site user.

In the user interface, the tabs were replaced with simple links changing the contents of most of the page.

 

Removing redundancy

 

It occurred to me that there was some duplication going on. In DocTool, RFC's and problems could be registered with information that might also be present if these actions would be registered in ProbReg.

I figured the latter would be better suited for keeping tabs on progress, while keeping stuff in DocTool would make it possible to establish relationships with specifications and such.

So I wondered if it would be possible to combine the two, and I came up with the scenario that DocTool would be the starting point, and when something registered there would be worthwhile enough to work on, it should be possible to transfer it to ProbReg. There would need to be a link between the two registrations, an issue in DocTool being traceable to the corresponding issue in ProbReg, and the resolution in ProbReg resulting in an notification back to Doctool.

For this I took out the possibility for entering some information in DocTool, and replaced it with a link to the ProbReg application. Also I had to find a way to get information from one app to the other, and it turned out to be surprisingly, almost disappointingly easy: I realised them with one app's view finishing with a redirection to a view of the other app, passing variables with the GET method.

Because I developed both apps separately, they are implemented as different virtual hosts on the same server (within the same domain though). Since it's all going through local dns on my home network, I have no idea how this would work over the web.

 
 
 
 

terug naar "python"

content and layout created 2010 by Albert Visser contact me