Monday, November 01, 2010

Doc Dep: A tool to handle the dependency of code and its corresponding documentation

As I work on Abu, I realize that documenting a project is a separate side project in and of itself. I started with a simple Idea.txt, and that has burgeoned into the following:
  • A readme.md (for markdown) for github's main page
  • A contents.md showing the contents of the codebase
  • A design.md for the design "discussion"
  • A user guide - WIP
  • A developer guide - to be created
  • A roadmap.md
  • A log.txt for my personal use - as a tickler for when i stop working and have to pick back up later.
  • A news.md (yet to be created) letting people know of recent changes
And what's interesting is the interplay between changes I make to the code (or design) and these documents. Each change in code/design obviously impacts one or more of these documents, but there's no easy way for me to keep track. Eg, change in design impacts the user and developer guides, the news file, and sometimes the readme and roadmap files. Any new top level directory added  changes the contents file and so forth.

Now, what if I had a way to say "this code file impacts these document files", so that when the code file changes, I have to change the corresponding document? That then, is the idea - DocDep - which will have:
  • A means to list all the documents in a codebase - some kind of config file should do, or probably a /doc directory could be assumed if we want to go CoC.
  • A means to represent the dependency between a file and these documents - easily done by creating a tag - embedded within a comment - in the files
  • A means to alert the developer when a change has occurred on a file, which therefore needs a change in the document file linked to it.
    • This could be as simple as generating a todo list by commit, Eg: todo: change guide.md to handle change in commit# xxx; Or...
    • We could go anal and prevent checkin of the code changes without the documentation.

No comments: