After playing with my documentation idea a bit, I discovered a serious problem: what I created looked great in Word, but all the comments existed only in Word, leaving me a bit lost when I looked at the source code itself. This is a problem; for many, the source code will be the first thing they see and the only thing they see. In many applications (fixing compiler errors, debugging) I'll be working with the source code. The moral of the story: the source code matters!

In particular, Knuth composed in a Web file, then produced both a .tex and a .pas (Pascal source file, whatever the extension was). However, neither produced file was editable or even very human-friendly. Instead, I now see that both the "pretty" format (in Word or whatever) and the "plain" format (raw source code) should both be nicely formatted and easily readable.

That is, I'm building a bridge between a beautiful representation of the code (probably HTML) and a functional representation of the code (as plain text). The beautiful form is easier to edit documentation and comments, insert diagrams, videos, etc. while the functional form provides a tight coupling with the compiler / debugger.

That changes everything in terms of my design.

Before I get too carried away with it, let me test-drive this idea by providing some example code. This is the beautiful form, taken from a unit-testing section of the document.


Testing
I don’t have a unit testing framework. So, I’ll develop what’s necessary as I go. There’s a framework for Excel, but it’s very tied to that application. Problems so far with the home-brew approach:
1. There’s no automatic test discovery; I have to manually add all tests.
2. There’s no setup()/teardown() facility
3. There’s no “clean the environment” comment. For example, strLastError can be polluted by earlier tests.

Source file split testing
A documentation file with no extension should produce an error.
Sub Test_SourceWithNoExtension()

First, create a dummy document to test with.
    Dim docSource As Document
    Set docSource = Documents.Add
    Dim strFileName As String
    strFileName = "Word documentation idea test."
    docSource.SaveAs fileName:=strFileName

Now, do our testing.
    OpenDocFile

Clean up by closing and erasing this old doc. If the test breaks, the developer must close it ma-nually. Time to look for a try/catch in VBA (On Error statement)
    docSource.Close
    Kill strFileName

Check that it worked. Errors are reported as strings, so check for the correct error text.
    Assert (strLastError Like "*Documentation file has no extension:*")
End Sub

Now, here's how I'd like to see this in the functional form (as source code). Since this is VBA, the comment character is the single quote '.

' <h1>Testing</h1>

'

' <p>I don’t have a unit testing framework. So, I’ll

' develop what’s  necessary as I go. There’s a framework

' for Excel, but it’s very tied to that application.

' Problems so far with the home-brew approach:</p>

' <ul>

'   <li>There’s no automatic test discovery; I have to

'     manually add all tests.</li>

'   <li>There’s no setup()/teardown() facility</li>

'   <li>There’s no “clean the environment” comment.

'     For example, strLastError can be polluted by 

'     earlier tests.</li>

' </ul>

'

' <h2>Source file split testing</h2>

' <p>A documentation file with no extension should

' produce an error.</p>

Sub Test_SourceWithNoExtension()

    ' First, create a dummy document to test with.</p>

    Dim docSource As Document

    Set docSource = Documents.Add

    Dim strFileName As String

    strFileName = "Word documentation idea test."

    docSource.SaveAs fileName:=strFileName

    ' <p>Now, do our testing.</p>

    OpenDocFile

    ' <p>Clean up by closing and erasing this old doc.

    ' If the test breaks, the developer must close it

    ' manually. Time to look for a try/catch in VBA

    ' (On Error statement)</p>

    docSource.Close

    Kill strFileName

    ' <p>Check that it worked. Errors are reported as strings, so check for the correct error text.</p>

    Assert (strLastError Like "*Documentation file has no extension:*")

End Sub

It's interesting that, to me, reading the first is much easier than reading the second. Not because of the HTML markup, but because a simple difference in font provides visual cues to divide the code nicely. It feels good to me to read the first! This is certainly what I'm striving for.

I haven't found a reasonably-featured word processor that read and writes HTML, though. Word includes lots of goop, but has all the features I want. I need to try OpenOffice and also Compser to see if they're reasonable. While I like several of the browser-based editors (Google Sites / Docs is great), the "allow now access to local files" paradigm seems to prevent their use in editing local files.