Best Practices for DataBlock Design, part three: The Value of Good Documentation



If you’re just joining us, welcome to the third and final installment of our series on good Argos DataBlock design. Our first two chapters covered Planning Your Ideal DataBlock and Getting The Look Just Right. Today, I want to talk about an often-overlooked, but equally important aspect of good DataBlock design—documentation.

When you’re building DataBlocks, it’s very important to keep in mind that you’re probably not the only one who’s going to interact with your DataBlocks. And even if you are, six months from now, you won’t remember what every piece of your design does, or why you designed it that way. Good naming conventions and clear descriptions can save other designers (or even just your future self) from confusion down the road.

Naming Scheme

As we’ve strongly recommended in a previous blog post, adopting a naming scheme can go a long way to help your DataBlock become understandable to other designers, and to yourself as you continue to develop. You can save yourself and others plenty of time if you follow some simple rules for naming your objects. As your SQL scripts will rely on these objects, name them as you are creating them. Don’t wait until after you have written all your SQL! Argos will not update the variable references in the SQL, and you may run into situations where your DataBlock will require quite a bit of editing to weed out every reference to a variable you may rename after the fact. A name also can tell you which form the object may be on, and what the object is allowing the user to select.

Here are some rules I follow:

For form parameters:

Example — parm_Main_DD_Term

First, I state that the object is a form parameter with ‘parm_’. As a reminder, no spaces are allowed in variable names, so an underscore is commonly used to separate words when naming.

Second, I will put the form the object is on. On DataBlocks with a single form, this may not be as important. If you have named your forms as well, simply put the name of the form here.

Third, I put the type of object as an abbreviation. For reference, I use:

BT (Button)
CB (Check Box)
CH (Chart)
DT (Date Entry)
DD (Drop Down List Box)
EB (Edit Box)
LB (List Box)
MB (Memo Box)
MC (Multi-Column List Box)
RB (Radio Button)

Other objects can be named in a similar fashion. However, labels, OLAP cubes, panels, scroll boxes and shapes are not truly parameters and do not show up on the Variables tab in the DataBlock editor. It may prove useful for you to name them, but it is less necessary than the other parameters.

Finally, I use a word or phrase that tells me what this object is showing me or allowing me to select.

For SQL variables:

Example – sql_Main_GetStudentID

I use ‘sql_’ to denote a SQL variable.

If a SQL variable is used on a particular form, I put the form name in the second position. If the SQL variable is not going to be used on a particular form, this may be omitted. Again, this is not as important if your DataBlock only has a single form.

Finally, as with objects, I use a short description or abbreviation that describes what this particular variable is doing. This helps distinguish the variable from all the rest.

DataBlock description

The last point I’d like to leave with you is to always clearly describe your DataBlocks and objects. This lines up with naming things properly, but design requires much more than that. To help with this, Argos allows you to put notes into the DataBlock. You can (and should) add a description to the DataBlock as well.

In your forms, you can use SQL and add labels to describe what an object does. Be as descriptive as necessary so that your end users don’t have to guess at what that object is doing. As an example, let’s say you make a selection for organizations. A list box that just has organization codes might be misleading. In the SQL you can add the account description as well to display for the user. Adding a label above the list box that says “Organization:” might be enough. However, if you could select more than one account, with a small edit to make the label say “Select Account(s):” you can clue your users in to the fact that you can select more than one account without writing explicit instructions.

If your users do need steps or instructions, considering adding an extra form they can reach where you can provide detailed instructions. On the other hand, maybe a short description near the selections is all the end users need. Your end user feedback will help you find the right level of information to include or exclude from your forms. You need to strike a balance between being informative and creating a simple and clean interface without the clutter of instructions.

Remember: You are the designer

While I can make suggestions and provide these tips, nothing in design is a hard fast rule. Each institution I’ve worked with has had different ideas, needs and rules. Meeting the needs of your end users is always key here. Communicate with your end users to get a feel for what they need. Be open to feedback, and always be willing to try something new to take your DataBlock design to the next level.

Like this blog?

You might also like this On Demand webinar:

Related Posts

Cybersecurity Trends and Threats in Higher Education

Cybersecurity Trends and Threats in Higher Education

It is undeniable that the historic events of 2020 created long-lasting changes in work and learning environments across the globe. In higher education, students, faculty, and staff realized that it was possible to successfully work, learn, and teach from home....

Evisions CO-OP: Top 10 Most Viewed Argos DataBlocks

Evisions CO-OP: Top 10 Most Viewed Argos DataBlocks

The Evisions CO-OP User Community is a collaborative place where clients can share ideas, experiences, development, forms, DataBlocks, and reports with their peers. To give you an idea of what fellow Argos users are doing and looking at, we present the Top 10 Most...

Navigating the Evisions Customer Community

Navigating the Evisions Customer Community

The Evisions Customer Community has always been an invaluable tool for clients. It serves as a resource for peers in higher ed to share knowledge and find answers. On May 7, 2019, a new community portal was launched. Why? Because we listened when our clients told us...



Submit a Comment

Your email address will not be published. Required fields are marked *

Share This