Have you written documentation of solution?

Hi, I am curious how many people write documentation of their solution?

If yes, how do you write? Or just leave comment in your script? Do you write down the business rule or why you choose this structure as your final decision?

If you have junior developers in your company, how do you make sure them understand what they are going to do as they may not be able to participate the meeting with clients.

I am wondering is it ok to just run a DDR analysis and look at the comment in the scripts?:thinking:

Any advice are welcome.

2 Likes

Hi @samfmp,

The extent of the documentation depends on it’s purpose.

Internal documentation ( developer oriented ) should be mandatory. No-one is going to criticise you for leaving too many comments in your scripts or explanations for relationships in the graph. Even if you work alone, documentation is an important part of the process.

I start each script and custom function with a statement of purpose: Say what it is meant to do. I also include a description of parameters and any external dependencies, such as a plugin ( # Depends On: plug-in name, version, and URL ).

If a script is long or the code is obtuse, I’ll use inline comments which someone should be able to read, without reading any code, and understand the purpose of the script.

Business Rules can be recorded in notes in the relationship graph. That is where they are often enforced. Notes are free and can be stored in collapsed state so they are neat and tidy.

Layouts can be used to store extensive notes too. You can stash a lot of information off-screen, so that it is visible in layout mode. That’s always a good place to keep layout specific information.

Field comments also allow you to describe the purpose of fields. Believe me when I say that it is not always obvious what a field is for.

I use the comment area of the table’s primary key to describe the reason the table is included. For example, this is the comment from the ID field of a table called Person, “this table stores the data that is always able to be made public. Potentially sensitive info is stored in PersonalInfo”

When you are working with others; junior, peers or seniors, you should have clearly stated requirements that are discussed in meetings to ensure that everyone understands the work they have to do.

A DDR is a great way to document your progress and to record a snapshot but it’s forensic, it’s not explanatory. It tells you what is there but it doesn’t explain why. Also, it’s pretty hard to locate your field comments and so on. Not user friendly.

I take a DDR prior to starting work and I take a DDR after finishing work. That provides me and my clients with a verifiable record of the database at the point immediately prior and immediately after I did my stuff. That allows me to say, “Here’s the output from the DDR, I added/deleted/edited X, Y and Z.”

3 Likes

Thank you for your detailed response. so did you mean you will make documentation internally, but not in an external files?

One more question, do you record the interviews with your clients, than team members in your team could listen and know what was going on even though they have not attended the meeting?

2 Likes

Ideally, there is a chain of documentation:

  1. process/business rule
  2. workflow
  3. implementation
  4. user guide

The process/business rule is a diagram, written in a way all concerned parties can understand.

The workflow defines how the process/business rule will be implemented.

At implementation level I rely heavily on comments in scripts and functions. Layouts are mostly self-explanatory.

For user guidance in bespoke solutions the famous tool-tips are quite helpful. A full documentation can be written by myself or the customer.

5 Likes

Thank you. For process/business rule and workflow, what softwares are you using?

I rely on OmniGraffle (on Mac). In the Windows world MS Visio is a common tool.

1 Like

Is there free software you will recommend for Mac?

LibreOffice has a drawing tool that is worth a try.

As much as possible, I document internally. External documentation is important but that is a different sort of documentation. The documentation I’m describing is developer oriented. If that was stored externally how will you access it when you’re on the road, at the client’s office, etc. ? And even when the documentation is available, it has to be read. There’s not much point in having a big warning in 32pt Arial, all-caps when it’s in an unopened word document on the Z drive.

I don’t take audio recordings of client meetings. I use a notebook, a pen and a pencil. I’ll take photos of whiteboards if I think I need to. Any important agreements will have to be put into writing, or are already in writing, so a recording is not necessary for that aspect.

3 Likes

Unfortunately tooltips on Webdirect are so slow to come up that users can miss them if they wave to fast.

WD is very challenging, especially in the case of complex layouts. I always recommend using the rich client (FMPA).

I prefer it as well but app is for client’s customers and hosted on aws.

@Torsten uses OmniGraffle (easily the best Mac drawing tool for this work and well worth the money) so he’s probably does not know that you cannot use LibreOffice’s drawing tools without suffering a headache. :slight_smile:

Try Yed, yEd - Graph Editor. I use Yed a lot because it’s cross-platform and it integrates with Confluence. There’s also a web version. I prefer OmniGraffle but being x-platform and integrated with web service work-tools makes Yed much better for teams and collaboration.

2 Likes

Ok, Thank you. I will try later and consider to buy OmniGraffle later. I will buy a 2empower development assistant first.:sweat_smile:

Agree with @Malcolm , LibreOffice is less comfortable to use. yEd is a better choice. It is free and cross-platform.

1 Like

Could audio recording act as backup of the meeting?

Let say you may miss something in the conversation, if you have one copy, you could play back and get the information?

I am not sure it is practical at all?

Audio recordings are good for preparing transcripts of meetings.
You will need to ask all attendees for consent before recording.

2 Likes

There was a similar posting at the FileMaker-Magazin.de - forum lately
https://filemaker-magazin.de/forum/beitrag/194860

Some of my ‘points’:

Documentation is ‘a mess’ because +/- nothing can be done automatically :crazy_face:

  • naming conventions… the ‘system’ of naming does not really matter, important is that the naming is always the same
  • comments wherever possible is important. But helps only if they are up-to-date (and not too long…)
  • a short description of the processes is important (from the user’s point of view; as detailed as useful…), could also be used as a checklist after changes (there are no easy test-robots in fm)
  • the most important functions/scripts can be added to that short description
  • analyzer… if something is not clear, we use DDR’s that we process using FMPerception (there are other abalyzers available, FMPerception is the fastest, by far)
  • layouts… often, we have a layout for the main description (‘how to’, etc)
  • integrated ToDo-list (basically, a ticketing-system, tickets->ToDo->ReleaseNotes. If there is some text in those ToDo’s, they serve as a manual…
  • we have a ‘manual-section’ integrated in that ‘ticketing-system’, divided in chapters, relatively short
  • flow charts (OmniGraffle, TouchDraw on iPad, etc.) might be really helpful
  • printed documentation was not that helpful here - not up-to-date, not ‘in the pocket’, etc.
1 Like

Many of the development techniques mentioned are also used by us. Better to over explain than under.

We will also add bright ‘developer text’ (which has its own style) to layouts and use a Hide condition of ‘1’ so that it is only visible in layout mode. This is especially helpful for overlaid buttons and other things that may not be obvious or for something very important.

We will also create either a dedicated table or just a layout with no records in the solution where we will add information that may not immediately be obvious upon returning to a solution at a later date, or for a colleague working on a solution, or for perhaps a data take on. If the information deserves it, we’ll create a table and use individual records, but if it is a few notes, then we’ll just use the layout background to add text to.

The ‘growing up’ phase really becomes apparent when sharing development or employing staff for the first time. Personal preferences have to give way to procedures and methods, that are agreed within the team.

We utilise OneNote on iPad Pros, MacBooks and Surface Pros/Books and their respective pens for taking notes during meetings. We have notebooks that are shared throughout our team via our Office 365 accounts, allowing information to be shared. Often the hand written notes are typed up to rationalise the notes taken and make the more understandable. No more lugging multiple notepads around and trying to find pages within them.

On workflow, we’ll usually use mind mapping for ‘unloading the brain’ and creating concepts. We’ll even use this to map out a complex calculation journey if needed (particularly if picking up someone else’s work). We’ve owned Mindjet MindManager for years, which is very good but expensive. There are all sorts of alternatives available.

Like many here, Omnigraffle is great for a less structured approach than mind mapping and is used for business process and pretty much any other flow where more control on the layout is needed. There are some good online alternatives as well and Omnigraffle Web will now allow Windows/Linux users to share data.

For clients and internally, where things are not carried out very frequently, but always need time to remember/work out how to do, we create our own PDF ‘Cheat Sheets’, that are a combination of text and screen shots, that save hours of unproductive time. We have used Clarify for this for years, but sadly it is not being updated to 64bit and the online alternatives are currently cost prohibitive for what we need. At the moment, we’ve reverted to Pages and use the standard Mac screen shot short cuts as outlined here: Keyboard Shortcuts to Capture a Screen Shot with Mac OS X | Information Technology Group and, from memory, add the Option key to copy direct to the clipboard for pasting.

For more technical work, such as setting up our Windows cloud servers, the whole process is documented in BBEdit in great detail. This is frequently updated as new servers and updates change the process.

FMPerception is used by us all, but we do not rely on this to communicate between each other.

2 Likes

I am using ‘Agenda’ very intensively for taking notes and tracking general processes

Drawback: Not multi-user (can be done, but not easy)
Cool: If You are on Apple, You can use Agenda on every device, wherever You are, synks via iCloud, automatically
Cool: Works on development (a lot of so called ‘gtd’ apps are more or less ‘shopping lists’)

Other apps like ‘redmine’ are not available if there is no network…

(Agenda became here the replacement for OmniFocus)

2 Likes