For user manuals, I tend to just use a web site, since they are naturally
hyperlinked.
here is one such user manual for a ms-access application (users don't know,
nor care that it is
in fact ms-access).
http://www.kallal.ca/ridestutorialp/index.html
As for a technical document?
Well, in most cases, that document should have been made BEFORE you start
building. however, that not normally the case.
The actually source code and application itself is usually the only
documentation you can expect to have.
However, a few things should be in order.
#1 on my list, and the FIRST thing I ask any developer to produce is the ER
(the data Entity relationships diagram -- in ms-access, that is our
relationships window). This is your "road" map, and as a developer, if you
don't know the table layout, then you really running blind.
With a good data map, the code practically falls into place.
So, make sure you have a NICE ER diagram laid out. I walked into to
companies that just spent over 1/2 million dollars on a sql project, and the
developers could NOT product a ER diagram, and were in fact not even using
the RI abilities of sql server. I could not believe what I was seeing!! As I
said, this #1 on my list..and if you can't produce a good ER diagram, I
going to give your developer a team a "F".
Here is a design time layout I used:
http://www.members.shaw.ca/AlbertKallal/Articles/PickSql/Appendex1.html
And, the final result in ms-access is here:
http://www.members.shaw.ca/AlbertKallal/Articles/PickSql/Appendex2.html
Now, the next question is your relationships window correctly setup to
*CONVEY* to a new developer your data assumptions?
Did you respect left joins, and inner joins when you built the
relationships? 90% of my joins are left joins:
A left join means that a query will return the "parent" records when the
child table HAS NO correspond record.
So, if we have Customers, and Invoices tables, a left join would give us:
CustomerName InvoiceNumber
AppleBee
Donought Shop 1234
Doughnut Shop 1344
Note how AppleBee does NOT yet have a invoice number in the invoices
table..but the query still returns the record. You have to use left joins
for lookup values when you drop in many tables (can't use standard joins in
this case).
So, with a left join, the corresponding child record DOES NOT have to exist.
Just think of "left" side can exist...but the right side does NOT have to !
A middle join, or so called inner join is the standard join, and BOTH tables
have to have a value for the join. The above would produce:
CustomerName InvoiceNumber
Dounought Shop 1234
Doughutn Ship 1344
So, in the above inner join, our customer name of Applebee does not show,
since that customer does NOT yet have a invoice record in the invoice table.
To make a left join, you drop in the tables (in the query builder, or the
relationship designer), and draw the join line to the appropriate filed
between each table. You then double click on the join line. You then click
on the join type button
You get three options:
Only include rows where the joined fields from both tables are equal
(this standard default inner join)
Include ALL records from "Customers" and only those records from
"Invoices" where the joined fields are equal
(this is our left join. So, our main table Customers will be returned in
this query, REGARDLESS if the child records (invoices in this example)
exist, or not!. This is left join
Include ALL records from "Invoices" and only those records from
"Customers" where the joined fields are equal
This sis obviously a right join....
For forms, and sub-forms, and related tables, left joins are quite
important.
If you look at the following screen shot, you can see that most relations
ships are this left join, and RI is enforced.
http://www.members.shaw.ca/AlbertKallal/Articles/PickSql/Appendex2.html
tblBgroup (booking group) for example may, or may not have payments made
(tblPayments). Thus, you can add a booking group, and NOT have to add child
records. However, full RI is enforced, and you can see the side ways 8
"omega" sign AND THE ARROW HEAD. The simple lookup fields are simply just a
arrow drawn, and no "1", or omega sign exists (tblPayments to tblHowpaid for
example is a simple lookup). It is GREAT that I can look at the ER diagram,
and instantly know if child records are required, or they are not!!
The tables that MUST have a child records can also clearly be seen. If you
go from the tblBgroup to the its parent table, you will see table
tblBooking. You can easily see that there is a 1 to many here also, but NO
ARROW head exists. Thus, when I create a booking, my designs will ALWAYS
ASSUME that a child records in tblBgroup (booking group) will exist (ie: I
must code, and assume that when I add a tblBooking records, my code also
assumes that a tblBGroup will also have to be added). In plain English this
means that when I make a booking (reservation), my code assumes that
you MUST have people in that booking. However, I most certainly allow
people to be booked, but not yet have made any payments. So, your
relationship(s) if done right should reflect the rules you as a developer
want to maintain. I should point out that a left join, or a standard
(inner join) both allow child records to NOT exist, but you still
should correctly set this relationship, since when it comes to making
reports, and writing code...I will know what my assumptions
were at the time (ie: do I HAVE to add those child records
for the software to function correctly. So, if I write code to
make a booking, all of my code thus assumes that people
are also to be added to the booking. Break that assuming
of mine, and likely my code will break).
So, the ER diagram can convey a lot about your designs. Down the road, I can
now look at that diagram, and when writing code, I will know if the design
can, and does assume if child records are required. If you look at that
table, it is VERY RARE that I require the child record. That application has
about 60 tables, and I think only 1 or 2 in the whole thing is NOT a left
join. Hence, you most certainly should set the relation in the window for
future reference, and also it will help you when you create a query, or a
report.
So, you can see that a HUGE amount of information can be conveyed to a
developer if you have a correct setup ER diagram. It is a simple tool,
and one of the great features of ms-access.
Between a good ER diagram, and easy to read source code, you have better
documentation
then MOST applications.
And, code it self should have comments. And, use the "tab" key to align up
variable defs so they are easy to read:
in place of
Public UserLogonName As String ' network logon name
Public UserMachineName As String ' machine name name
Public UserInitials As String
use:
Public UserLogonName As String ' network logon name
Public UserMachineName As String ' machine name name
Public UserInitials As String
Is not the above MUCH more easy to read?
So, you typical defs might look like:
eg:
Option Compare Database
Option Explicit
Public gblTour As clsRides ' global class tour object
' used to "pass" between
' forms - currently not used!
Public UserLogonName As String ' network logon name
Public UserMachineName As String ' machine name name
Public UserInitials As String
Public gblPstRate As Currency ' pst rate
Public gblGstRate As Currency ' gst rate
Public gblRstGstRates As Recordset ' date rate gst lookup table
Public gblAllowMultiForms As Boolean ' allow more then on copy of
' same form to be open
Public gblBookingForms As New Collection ' collection of above open
' bookings
Public gblrstTourOptions As Recordset ' list of tour options
Public gblstrBackEndPath As String ' unc path name to back end
Public gblstrInvoicePtr As String ' name of invoice printer
Public gblLoadDate As Date ' date of local computer at
' program run time
Public curGstRate As Currency ' get rate based on todays date
Enum BookAction
BookToTour = 1 ' book to a tour
NewTourOnExistingBus = 2 ' book to existing tour bus
BookToFriends = 3 ' book with friends
NewTourAndBus = 4 ' new tour and new bus4
Combine = 5 ' combine tours
End Enum
So, just make sure you have comments when you NEED to have them.
In code, I will opften point out things that are NOT obivlery. eg:
Public Function BusTours(AddOne As Boolean) As Integer
' loads pick up groups, and returns number of pickup groups
' if addone = true, then ADD A GROUP if no groups....
' m_TrouGroup id must be set before calling...
Dim strSql As String
On Error GoTo BusTours_Error
If Me.TourGroupID = 0 Then
Exit Function
End If
strSql = "select * from tblBusTour where " & _
"TourGroup_id = " & Me.TourGroupID
Set m_rstBusTour = gdb.OpenRecordset(strSql)
The above code is not much, but I do explain TWO critical things that
developer would need to know
1) the class member "m_TourGroupID" *must* be set before calling
(I know this is a class object member, because a common naming
convention is to prefix your class "members" with a m_
2) I explain the use of the parameter AddOne
I don't think you have to go "huge" on a naming convention, but whatever
approach you adopt, try to be consistent. And, add comments for things
you CAN NOT figure out by just looking at the code (eg: above you MUST
set m_TourGroupID before calling).
So, just make sure you ER diagram is in order, and have some
comments in the code where you need them...
A huge large printout of the code, or some huge technical document will in
most cases NOT be any more useful the actual source code. You just need
to have clean readable source code...that is the BEST technical document
you can have...
