Documentation System

I've had a need at work to create some online documentation.  So I searched around and found PHP Doc System.  This software allows you to create documents by building a table of contents file and then you make "modules" for each page represented in the the TOC.  This isn't software for the average guy as it requires at least a basic knowledge of PHP in order to use it.  I'm not sure, but I think I have that covered —but feel free to argue otherwise!  Anyhow, I did some hacking on it to add a few improvements and also to get it to work with our stone-aged version of PHP that I'm currently strapped with at work.  (Another story unto itself!)  I sent these changes to the author, Alex King along with some ideas and suggestions regarding building a DB back-end system for it.  Alex was kind enough to reply and seemed generally accepting of my changes.  Of significance though was the DB back-end.  He lists this as something he'd like to add on the web site, and in his reply he seemed interested in, but only because he realizes that that this would simplify adding the  search functionality.  But he seems reluctant to do this as he wants a stand-alone search ability for the static pages.  A reasonable consideration I would say.

Since corresponding with Alex, I've made further changes to the code to meet my immediate needs at work.  But although I'm happy with what it churns out, it's less than ideal.  I've also been looking at the documentation for PolarBlog and although I think it is reasonably complete and contains lots of useful information, it's somewhat disorganized and unwieldy.  Thus I've been contemplating rewriting it, possibly using Alex's PHP Doc System.  This would be an improvement and also allows the ability to generate static documentation to ship with releases.  But I don't find this solution or any others that I consider "complete" enough to easily generate online documentation.  I don't want to rewrite it only to have to rewrite it again because I'm still not happy with the end result.  Thus I've been thinking…

What about writing a new system largely from scratch, but incorporating some of the concepts of PHP Doc System?  The analysis:

Pros

  • DB Back-end
  • Unlimited TOC element nesting.
  • Easy search for dynamically generated content.
  • Collapsible TOC elements.
  • A good deal of good code reuse (or at least concepts) from the PolarBlog project.
  • A desire to do it!
Cons
  • Development takes time!
  • Managing yet another project.
  • Reduction in time available for my current projects.
  • A reluctance to do it!
I've already put a reasonable amount of spare brainwork into how some of this would work.  But I would definitely be outlining the big picture a bit further before embarking on this journey.  I also have a couple of other things currently on the development horizon…

PolarBlog V1.5.0 will be released this coming Monday.  The V1.6.0 release will definitely contain Trackback support.  Other features that I'd like to implement that may be in this release or the next couple releases are Pingback support and the ability to post entries via email.

The MyClient project has been idle for quite sometime.  A couple of weeks ago I began work on a complete ground up rewrite, starting with a new tabbed interface window.  This adds some flexibility to the program as well as updates the interface to a modern design.  This project really isn't overly complicated, but these things always seem to take more time than one anticipates!

Thus I now ponder "PolarDocs"…

The Arms Race

The Arms Race

Day after day, it's always the same
Someone's going against the grain
Paper brings word of another joining the chase
All out to be, the superior race
Lead, blood and tears, they bring up the rear, as the great gears of the war machines turn.

Some day they'll learn, we're all equal in some way, shape or form
But it'll be too late, we all know our fate
We're all going to die because of one's hate for another in that great arms race.

8/6/1981
12:25am