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"…

Comments

  1. Tim said:

    What format are the static docs in? Might be good to be able to output them in OpenOffice format. I here that's pretty simple since OpenOffice standardizes on XML.

    I'd offer to help, but I'm still in the middle of getting core features into PressPointe so I can release the first version to the public.

  2. Kevin said:

    The static docs are just standard HTML.  I hadn't given it a lot of thought, but outputing to other formats would be a possibility.  All of the content would be stored in the DB so it could easily be exported to various formats.  The only catch would possibly be if there are HTML tags within the text, which there likely would be.  I guess one could work around/convert those though.

    I take it that you consider this a somewhat worthwhile pursuit being you've expressed some interest and even the prospect of possibly helping at some point.

  3. Tim said:

    Well, the one thing I question is if this system does more than I can do with a Wiki. After all I could just disable the user ability to modify the Wiki content. Or could you just modify an existing CMS to do this. What does this app do that a CMS or Wiki doesn't?

  4. Rob said:

    I would be happy to help you with this Kevin. Although as it seems there are a few others out there as there is Blogs but you seemed to be keeping up with the Benjermins!! I would highly suggest as Tim mentioned about outputing XML since there are alot of apps out there that will support this! Would just need to put everything on the table to see what we want to accomplish and go from there.

  5. Kevin said:

    What I'm talking about building really isn't a blogging application, but more closely related to a wiki as Tim suggests in the thread above.  I guess I would consider it a "mini-CMS", but with the ability to generate static HTML, XML or possibly other formats at some point.

    I hadn't thought about outputing to XML previously, but that would obviously have some merit to it.  But then you are looking basically at a DocBook editor I think.

  6. Kevin said:

    I guess the short answer is it really doesn't! ;)  As I mentioned to Rob below, it's more of a "mini-CMS" for writing technical (or other) manuals.  It is somewhat wiki like, but I've never seen a wiki that churned out a decent TOC that I've  liked.  I don't know.  Maybe I should be looking more at that as opposed to reinventing the wheel.

  7. Tim said:

    The recent and previous issue of PHP Architect (http://www.phparchitect.com/) has a great article about creating OpenOffice files from PHP.