I'm very unhappy with the way I have contact set up here and at my business's website. One drawback of using static sites only is that I can't have any dynamic processing and so can't set up a form that sends an email--that option is sort of available but it's terrible and doesn't really work anymore.

There are other businesses I could pay to do this processing. These businesses set up a system whereby you can have your form content sent to your email in a more secure way. Web3Forms is an example. The objective being to:

  • hide your email address from wouldbe spammers
  • have a contact form that works if the user doesn't have an email client and/or email.

Web3Forms seems decent enough--I've not tried myself--but I'm also in need of a professional portfolio better than a work history in enterprise and medical. I also have to admit that that history doesn't have a lot of requirements analysis or planning in it and is mostly development, design, and mentorship. A contact form is a simple enough project to do some exercising of my own, play with some ideas in project management, maybe instruct a bit, and showcase what I can do in this area.

What's the project going to be?

I've started a lot of work in requirements analysis and design that I'll be talking about in this entry later. The brief of it is though that this will be a secure contact form server that I can configure for myself and my website clients (when I get some) that offers the sort of guarantees I want from such services. In doing so I'll be leveraging some quality controls that are really just in my head for now but are meant to protect user data from any and all unauthorized access.

In this I want to document some of my thoughts on how to design such systems and ensure that they work the way you say they do to the best of your ability. I can't go so far as to guarantee a lot of things because I don't have the expertise to say things like whether or not the claim that this or that algorithm is quantum secure is true or not. I have to trust that the experts are telling the truth. I can do my best though to apply their work as intelligently as possible.

Some things I'm doing the long way because I don't know of the right tool to do it the easy way. I'm sure these tools exist and can be tied together the way I want, but so far I've not found that solution and I need to get something done so--the size of this project makes it still possible to do what I want the way I want.

Starting out - Design Inputs

The 62304 process has "Design Inputs" feeding a "Design" process that results in "Design Outputs" that are then used as inputs to the next process in the Software Development Life Cycle (SDLC). Some managers and quality control people take this to mean that you have to do one, and then the other. I do not believe this to be the case, especially since the standards say so. What this tells us is that there's a dependency relationship here.

You indeed do have to start the process of requirements gathering before you can start designing anything.
Otherwise you're just desiging a whatever and don't even know if it has anything to do with your product. But this relationship can and should feed back on itself. So your Design process may have Design Outputs that are themselves Requirements that get fed into the Requirements Analysis process that creates the Design Inputs to begin with.

So it's an iterative thing. You do some requirements analysis and come up with some basic requirements and then you do some initial design work to come up with some architecture maybe, do some research into what some of the ramifications are, and then feed that back into requirements with your findings. Then this loops back on itself and at some point you actually start trying to implement the design, which will be changing but when you're here you know enough to start and see if your assumptions are correct. They won't be. This will feed back into design, and this may result in more requirements and these may in fact conflict with others.

At the end of this you need a correct implementation of a coherent design that responds to the requirements.

So I started out with some "Design Inputs". Standards don't say what these are so I'm borrowing a little from SysML and a little from some of the processes I saw when doing medical software development. I think maybe there should be more up-front test design than I'm doing, which was just to jot down some "acceptance criteria" but when the whole thing is done and documented those criteria I think will translate into actual tests or at least be linked to them. The object here is so that those who desire the product have thoroughly thought out what they really want and how they'll tell if they got it. The more detail the better but generally you don't get to hash it all out and that has diminishing returns on quality and coherence of design.

The Project

The Project code is here. I'd first like to discuss a couple of things I did here to help with quality. The first of these is a standard development environment that is easily installed and entered. The second is the assertion of commit checks in the form of pre-commit hooks.

For the first, I'm currently using the Nix package manager and devshells library along with a docker image to support some python utilities. The devshell setup lets me activate some commands on entry, pull in commands the developer may not currently have in their environment, and set up some aliases and commands of my own. In my case the main command I need at this time is Jupyter Book version 1 because that's what I'm using to document my project.

For the second part I'm using the previously mentioned pre-commit plugin that I install with Nix. I do expect I may run into trouble here since it's Python based and Nix doesn't play well with Python but for now it's working. I add the conventional-pre-commit plugin for it to make sure I always use Conventional Commits when I commit. Why Conventional Commits? Because what the format is isn't as important as that there is one and it's not worth thinking about too much. That standard covers pretty much everything that needs covering so there you go.

Yes, the hook has already irritated me but I'm keeping it. Using Conventional Commits will allow me to automate things like release numbering, changelog generation, etc... Having thoughtful commit comments is really important to keep an informative history. The Conventional Commit format gives you some reason to think about what the commit content is going to be and helps you with some basic things you really need to include while encouraging more. This is not something that should be forgotten about and it's going to be central to my own Quality Management System. My own comments may not be the best always, but with this in place I'm at least giving it some consideration. Have a look:

Let's see those Design Inputs

Here is the version I would have put forward as a first attempt, though there would have been more back and forth during this process with the actual client to come up with these. On my own I put on both hats a few different times.

As you'll note, there's really only one feature requirement in the entire thing: take form input and deliver to the user. The rest of the requirements are largely about the security features used to try limiting how much this thing costs me to run, how much it spams the user, and that it NEVER turns into a spam source for random people.

There was a few times when I really had a particular implementation in mind. I tried hard to discourage myself from most of these because, and this can be hard for a client to hear, how the thing does the thing isn't the important part for this process. The design process really does need the freedom to reach out and find the things that will best implement exactly what is desired, not a pre-concieved notion of what that will be. It's very difficult to do sometimes and it's not always clear you are focusing on an implementation rather than on what you actually want, but it's very worth making sure you think long and hard about it. In the end I ended up with quite a few less, much more manageable requirements that say exactly what I want done.

This is a first draft and I'm not the best at making clean documentation but it should at least be clear.

Design and planning

Next time I'll talk about the Design and Planning I've done previous to writing this blog. In the meantime I'm going to start on actual coding.