Look at Me, I’m Invisible!


This project is really exciting for a number of reasons. The extensions to Fileman are exciting. The improvements to Lab are exciting. The opportunity to engage OSEHRA is exciting. Developing a project for VA outside of VA is exciting.

I, alas, am working on the non-exciting part of the project. I’m doing the documentation. I’m working on the afterthought, the bit that nobody really finds all that interesting.

Oh, I know. It’s considered bad form to say out loud that documentation is boring and stupid and nobody likes it. It’s more polite to protest that of course everybody cares about documentation. Which is why so many projects do documentation at the last possible second by throwing a bunch of stuff together more-or-less randomly. Because they care so much.

I’m mostly just teasing here. Yes, documentation is often an afterthought, but I think that, in principal, most developers would rather have good documentation than not have it. They just don’t want to be the ones to have to do it.

And, from the point of view of somebody who writes stuff for a living, they shouldn’t have to. Okay, they need to write down the basic information, but the task of organizing it, formatting it, and making it accessible to its target audience? That stuff should be done by a writer, not a developer. Developers have some pretty awesome skills, but explaining things to people usually isn’t in their skill-set.

It makes sense, then, to bring in somebody like me. Somebody who isn’t a developer, but who (usually) can follow what they’re saying. Somebody who nevertheless is more of a writer than a techie. Somebody who, unfortunately, will be invisible most of the time, because the really interesting stuff is happening elsewhere.

I’m looking forward to producing the documentation for this project, and I think our results will be worth looking at. Hopefully even worth imitating.

In the meantime, I’ll be over here. Invisible. 



I see you!

George Timson's picture

I have said for years that FileMan isn't much as code (after all, it's written in that horrible MUMPS language!), but it's noteworthy for its great documentation.  The VA effort back in the 1990's to document FileMan in HTML still amazes me in its thoroughness and accuracy, and yes, I use the documentation all the time, even though I wrote a lot of the code myself!

As most of you know, the VA documentation can be found at http://www.hardhats.org/fileman/u1/index.html. 

It is my fervent hope that the work we do on this OSEHRA project can be documented in a manner similar to, and hopefully integrated with, this HTML production.


--George Timson


We have two documenters

Rick Marshall's picture

We have two documenters working on the FLAP project.

Ms. Ice, who has just introduced herself, will be focusing on the formatting and explaining the content to create the .doc, .odt, and .pdf files. She'll be drafting Sam Habiel and me throughout most of November and December to help fill in the content based on all the fine work you've done on MSC Fileman. We'll be going through your Read Me file and your spreadsheets and for each item figuring out what needs to change to bring the manuals up to date. Given a thousand changes you've made since Fileman 22's release and some additional ones we're adding for Fileman 22.2, Ms. Ice has her work cut out for her.

In parallel with this effort, our second documenter, Duglas Kilbride, will be working on two things. One is finding opportunities to develop new diagrams to add to the manuals to help visually explain things. The other is reworking Kathy's content to come up with a complete set of up-to-date HTML manuals for Fileman. Mr. Kilbride is already wrestling with HTML-specific problems like the changes in the HTML standards since the 1990s, which will necessitate some changes to how we structure them. He was just describing some of these issues to me today, and he'll be blogging about it soon.

Part of the reason we put two documenters on this project is that File Manager has a long history of attention from highly talented, hardworking, and dedicated documenters in VA, so this project has a high standard it has to meet. Every previous Fileman documenter has not only met the standard of their predecessors, but has found ways to improve upon them by making the documentation more complete, more user friendly, or more navigable than in the past. We're looking to do likewise.

--Rick Marshall


document generation?

Christopher Edwards's picture

Has there been any effort to look into document generation like sphinx (http://sphinx-doc.org/), LaTeX, etc?

Example Sphinx documentation:  https://github.com/OSEHR/M-Tutorial you can browse the source and github will render the pages or you can clone it and run it on your own machine.


Relevance of PLAIN to Documentation effort.

DAVID Whitten's picture
I found a guide to plain language writing that I would like you to review and give us some feedback.A lot of it looks pretty straight forward, but I don't know how easy it would be to follow these guidelines. One of the things that I'd like to see at some point is crosslinking documentation to the particular code that implements the behaviour documented.  In the case of programmer APIs, it is common, but in user manuals and descriptions, it is rare.  Perhaps well chosen hyperlinks (or using old technology, footnotes) with a particular icon that warns the casual user that this is a link to technical information might be a good visual way to present it.  From a code and documentation maintenance perspective, following the links backward would make it easier to keep the various parts up-to-date when changes occur. Have a great day!
Dave P.S. The documentation I refer to is at:



PLAIN Is Interesting

Kathy Ice's picture

Thanks for the link, Dave. The PLAIN information is really interesting, and includes a lot of good advice for writing readable documents.

I think it could be condensed, and organized a little better. Some of their techniques, in my opinion, would be difficult for people who aren't familar with some of the finer points of grammar and language. It does no good to tell people to avoid the passive voice when a lot of people aren't sure what that means.

I think it would be useful to work up a kind of graduated set of guidelines. Start with things that everybody could and should do, then move on to intermediate and advanced techniques for clearer communication.