Providing documentation for macros

Making macros user-friendly : Providing documentation for macros

Providing documentation for macros

To make a macro as user-friendly as possible, you can provide documentation for it.

One solution is to create a Readme file or a printed manual. Another solution is to incorporate the documentation directly into the user interface for the macro, but this method uses up valuable on-screen “real estate.” Yet another solution is to create an online Help system, but this method requires special tools and a fair amount of additional work.

Perhaps the simplest way to provide macro documentation is in the form of a plain-text file. In fact, upon installation, a macro project can create a registry value that points to the location of this file. In VBA, the following function can be used to open a plain-text file (where the parameter file provides the full path to the file, such as C:\ReadMe.txt):

Public Sub launchNotepad(file As String)

Shell "Notepad.exe" & " " & file, vbNormalFocus

End Sub

A much more powerful solution is to provide documentation in HTML format. HTML provides numerous benefits over plain-text, including support for graphics and for hypertext links (such as to specific locations in the document — for example, index.html#middle). In VBA, the following function can be used to open an HTML file (where the parameter url provides the full path to the file — such as C:\ReadMe.txt — or a URL for the file):

' Put this Declare statement before all Subs and Functions!

Declare Function ShellExecute Lib "shell32.dll" _

Alias "ShellExecuteA" (ByVal hwnd As Long, _

ByVal lpOperation As String, ByVal lpFile As String, _

ByVal lpParameters As String, ByVal lpDirectory As String, _

ByVal nShowCmd As Long) As Long

Public Sub launchBrowser(url As String)

ShellExecute 0, vbNullString, url, vbNullString, vbNullString, 5

End Sub