BEST PRACTICE Documenting proceedure

[ECEK]

I always create a word doc and leave that in the same folder. Be great to embed it into the database.

What do you do?

 

[arnelgp]

without making the db big,
add a field to a table then
add the path and filename (linking) of
the doc to the field.

have you seen my Office doc
viewer db (i posted here, code sample).
you can view .docx, pptx, .xlsx with
the viewer. and diretly you can
edit the doc there.

 

[Gasman]

I have a hyperlink on the bottom of the switchboard to a word document that explains to others how the system works?
We'll see how good it is when I go on holiday next month.

 

[The_Doc_Man]

I always did TWO documents.

One was "developers only" and stayed as a separate file in the development folder (because I used staging folders... DEVELOP, TEST, PREP, PRODUCTION). This contained discussions of WHY something was done as well as any special comments on HOW it was set up, and often included a step-by-step overview of any process that involved more than just a query or a really short procedure.

Because I tend to compartmentalize things, each general module had a separate sub-header. I was using the 1., 1.1, 1.1.1, ... numbering scheme. General Modules was usually my chapter 5 and each named module was 5.x, and then if there was some particularly important subroutine or function, it was 5.x.y. For my biggest project, I guess maybe 20 such special routines got their own separate header. The simpler stuff got a slot in a (Word) table that listed entry point, inputs, and outputs.

But there was a second document on my biggest project. I had a "How To" manual that explained what the user could do and how to activate or reach that function. The document was Word-based, had lots of named bookmarks, and it was full of pictures, screen-grabs, etc. One of my modules had a subroutine that would Open the document in Read-Only mode and put it on top of the window stack, using a GoTo Bookmark option so it would jump to the right page for Help. I had a table of bookmarks, some of which were marked with a Form name while others were marked with an asterisk. When you clicked the Help button, another form popped up and presented a list of entries that you could select, with the form-specific items first and the general (*) topics last. Pick one and the form "did its thing" to open the "How To" document to the right page. Then just close that window when finished reading and you were still on the same form (and same tab, where applicable).

On earlier projects, I wasn't that extensive - but still had a "Theory of Operation" and a "How To Use It" document.

 

[CJ_London]

Like the Doc I have two manuals - a user manual and a technical manual. I used to have a link from each form to the relevant page/section in the user manual but of late have grown lazy and the link opens the whole manual - reason is it became a bit of a millstone to keep the links up to date.

The technical manual still exists, but is now much shorter - much of it is now embedded in the code as comments.

And yet - nobody every reads them before asking me 'how do I...', 'what's this for...'', 'Can we do....'

 

[Uncle Gizmo]

I have a very old system somewhere which uses a database table and a popup form. You place a button where you want the user to be able to easily access help. You can have buttons anywhere, as many as you want. Each button has a unique code that takes you to the right record in the table and displays the popup form. There is also a field on the pop-up form for user feedback.

 

[The_Doc_Man]

And yet - nobody every reads them before asking me 'how do I...', 'what's this for...'', 'Can we do....'

Are you sure you didn't work in my Dept. of Defense office?

 

[Minty]

Don't bother.
Show the only person that listens and will actually use the system in anger, and get them to make some notes.

When they leave repeat the operation with the replacement.

Put sarcastic comments in your own code, as you're probably the only person that will laugh at them years later.

 

[MarkK]

I run everything off the ribbon, and I load up the ribbon supertip property with everything the user needs to know.

 

[Pat Hartman]

I find that systems that implement the work process of the department, can get by with little to no user documentation. The users train the new people in the department procedures and the application simply implements them. I generally make some documentation anyway because sometimes there are subtle features that need explanation. I load the documents into the folder where the BE lives and add links to the documents from the application menu just in case someone has an ardent desire to read them. Same with the technical documentation and like Minty, I also write sarcastic comments in code.

If you want to embed the document in the application itself, use a table in the FE because it is FE changes that will dictate documentation changes and you want to distribute the updated documentation with the FE. Use a rich text control and a memo field for each. That will allow you to pretty print and avoid the issues of embedded Word or Excel documents.

 

[The_Doc_Man]

Excellent point, Pat. If the app matches what the department does and uses the nomenclature commonly applied therein, "How To" is used less often - and needed less often. It comes back down to the THIRD document, which I and many others omitted - the initial design assessment. If THAT is accurate, you can implement reality. If you shoot from the hip, all you implement is a fairy tale.