Universal Software Standards FTW!

For a while now, 4 years to be exact, I’ve been working on multiple projects within a huge company. It’s been a roller coaster to say the least, and the feeling I remember experiencing the most when having to create a new piece of software, that was supposed to serve other teams as well, was (and still is) the same: uncertainty.

Somehow, the team and I needed to architect an application or library that should work as good as possible, cover all use cases as perfect as possible, be tested as much as possible and be as flexible as possible to be prepared for any turn of events. And, as if that was not enough, it should have the best way to interact with a third-party application or library without having any time to figure out how it is constructed or even know which third-party app or library could potentially require doing so.

The years passed, the situation remained. But then, this company decided to changed its DNA: from license-based to subscription-based. And that came with a whole new different way to think about software. In short, the most important thing to do to be successful with this new DNA was collaboration between peers in order to achieve the best synergy possible between products.

This new direction sounds really good, and I want to be part of it for sure, wouldn’t miss it for the world… but the uncertainty I felt is not going away that easy unfortunately. And I wanted to do something about that, and not just for myself, but for every other co-worker as well if I could. Then, I remembered another change of DNA I experienced recently as well.

I work for this huge company through Globant, and it recently changed its DNA too in order to not just injecting innovation to its clients as we all grown to do, but also “create digital journeys that matters to millions of users”.

In this case, I’m interested in doing that for my fellow co-workers, because a good customer experience starts with a good employee experience, and by extension, a good customer experience starts with a good developer experience.

That is how I eagerly started thinking of a plan that could eradicate my deep-set uncertainty, an accessible plan, easily extendable and astonishingly scalable. Not an easy task if you ask me, but I love challenges.

This is what I came up with… ground rules in form of standards.

What is a Standard?

According to Wikipedia, a Software standard is:

“[..] common format of a document [..] accepted and used by one or more software developers while working on one or more than one computer programs. Software standards enable interoperability between different programs created by different developers.”

The key concept for this initiative is “interoperability”. Being able to generate a piece of software that followed pre-established conventions we all agree upon to:

• measure quality in some way;
• assist a developer in understanding what the piece of software provides in order to facilitate usage;
• provide an understandable and universally accepted way to collaborate on any type of project;
• promote a healthy way to extend any software when collaboration guidelines are followed;
• bring up to speed any new developer by reading the standards applied.

In essence, a standard should describe best practices, taking into account latest trends on how to develop a piece of software so that it works as good as possible. It should describe every process to create the most interoperable software as possible, including processes that could assure its quality as well as procedures to publish so that it becomes available for its usage.

How should it work?

First of all, these standards needs to be developed by the developer community, each one contributing constructively on any aspect on any standard they acquired knowledge about in order to be able to contribute towards generating valid, up-to-date and usable standards.

Secondly, by its collaborative nature, a standard cannot be imposed, crafted single-handed and distributed as a commandment. Any interested party should be able to contribute freely, following collaboration guidelines to propose changes, others could up-vote or give any sort of feedback so that ultimately certain designated authors can approve those changes to be included to the standard.

Last but not least, standards needs to be promoted and viralized inside its community so others could know they exist, pitch in to existing standards or create new standards and apply them. There is no use if just a bunch of people know they exist and adopt it on their projects, the more the better. We all know the following XKCD…

Not to mention that ideally any third-party app or library consuming your piece of software needs to know they are consuming something well made, safe and stable, and so on.

So, summing up:

1. Community-wide
2. Community-driven
3. Community-promoted

Let’s dig in into how could we solve these aspects.

Community-wide

I’ve been thinking about which tool fits best when we talk about a developer community. It’s definitely not Wiki pages, they are difficult to maintain and not very intuitive for developers. Well, a very intuitive tool for developers that is also available is Github. Developers already know how to use it, there is a pretty neat established way to collaborate through Pull Requests, versioning is built-in, it provides a way to generate viewable and presentable content through Github Pages if needed and it handles fine-grained permission and security. So, in order to reach the majority of the audience to become community-wide, using Github is the way to go.

Community-driven

As mentioned before, there is an excellent established way to collaborate through Pull Requests. Also, Github Issues provides a really good way to interact with a standard in the form of a repository. These Github Issues could be categorized with tags and promote a healthy discussion. Basically, the developers could own their ideas and share them easily, driving the whole initiative forward.

Here are some thoughts:

• I joined forces with the already created “Standards” organization on GitHub to help shape this initiative there. I even created a logo for it:

• In that Github Organization, there should be instructions on how to create a standard. A standard about a standard if you will. Let’s call it meta-standard.
• In order to propose to create a new standard, a new Issue should be submitted on the meta-standard repository including the correspondent arguments on why it should be created so it could be discussed and approved.
• Once a standard was approved to be created, someone can start working on the standard at a new repo on their profile
• Once the authors are satisfied with it, they can ask the meta-standard’s validators to review the repo to see if it complied with the meta-standard
• There can be extra work to be done it can just be approved, moved to the Organization, create version 1.0.0 of it, add a “meta” standard badge with the corresponding version to which the new standard was based on linking to the approved ticket.
• If a standard gets updated, it should follow a strict semantic-versioning pattern where based on v1.2.3:

1. means something fundamental changed from the previous version, major changes that totally changes the way the standard was
2. means something not that big changed, the base is still the previous version but a section was added or modified
3. means something pretty small changed that improves the standard but does not add or remove any section, mostly wording changes

Of course that there should be an open channel to interact with people knowledgeable about the standard initiative, that’s where a Gitter comes in handy.

Community-promoted

It is very important to let others know about the initiative, not only by peer-to-peer interactions, but also include visual aids; that are those badges I mentioned earlier. This is so that others could verify that certain library follows best practices that a group of specialized people put together collaboratively, and also, to create the urge to do the same thing and apply a standard or create one.

This kind of behavior is already installed on the Github community and it uses badges:

These are little images that informs something very specific, and are added to the top of the README file.

Its usage would be:

• The authors of awesome-library-X on Github that follows standard-X submits a Git Issue on standard-X repository to ask for validation
• The standard-X validators can proceed to validate awesome-library-X complies with the standard and present the results in the submitted Git Issue

1. If something needs to be modified, the validators can update the Git Issue to have the maintainers of awesome-library-X work on it
2. If everything looks good, the submission is approved and:

• the submitter needs to mandatory watch the standard repository to keep track for any standard updates
• the submitter needs to include a badge at the top of their README file specifying which standard does awesome-library-X follow and which version, linking it to the approved Git Issue to certify it’s a valid badge. As an example using Shields.io badge open standard(*), this could be the badge for a javascript-library:

(*) Shields.io open standard is a project that could potentially include a new GitHub integration to support this initiative. Also, there is a dependencies tracking open standard over at David-DM.org that could also serve the purpose to track if the latest standard is applied along other dependencies.

What’s next?

1. Receive feedback about this initiative to adjust what’s necessary
2. Have other people excited and willing to help with this initiative
3. Work on the meta-standard while also working on the first standard that complies with it, ideas welcomed.