The Art of Open Source

What is Open Source?

By definition according to opensource.com (supported by RedHat) open source refers to something people can modify and share because its design is publicly accessible. Lets think about this for a second, specifically the part that says ‘something people can modify’. That is an interesting concept; does this mean that open source projects are not finished work? Are they merely a starting point, a skeleton template if you will? I think this is the one thing that some people out there struggle with and why for some there is a difficult transition from closed software to open source software. Hopefully by the end of this posting I will have created something others can use to help understand the art of open source.

Open vs Closed Source

What are the differences between open and closed source software? Is one better than the other? Does the support most closed source solutions give you justify the cost? These are all very real and very valid questions that I find I am asking myself more often than not these days.

Early in my career I never used open source software…for anything. The companies I worked for just didn’t use it, it was all pay to play and at the time I didn’t know any better…or worse depending on how you look at it. As I progressed in my career I learned of open source projects that would do the same function as many of the paid solutions that were currently in use; some of them were even the upstream of the paid product that was in place. So I asked myself, why am I using the paid downstream when I can get the same thing for free?

When deciding whether or not to go the open source route there are two things to consider immediately. The first and most important being risk. What is the risk to the business? If there is an outage or bug what is the impact if something goes down? How quickly can I or my coworkers fix the system without paid support? These are all important questions when talking about the enterprise. The second is always budget. Do we even have the money for a new paid product? Does the functionality and support justify the cost? Lastly it is always important to decide whether it is a growing project with a thriving community. The worst thing you could do is to buy in to a project with little community support and eventually have it die….Candlepin?…Hopefully RedHat will revive that…Talking to you Katello guys.

Anyway, I digress. But the point is, when all your questions are answered, you have all the information at hand and you are about to make your decision there is one last question to ask yourself. Are you going to be involved in the community? Are you going to become a subject matter expert (SME) or as I like to say Lead Knowledge Dropper (LKD)? Are you willing do dig through source code, test new patches, run RCs in dev? If you can’t answer yes to at least a majority of those questions then you need to open up that check book.

Open Source…Bringing People Together

Lots of people complain about open source projects not having good support, or not doing everything they want. There is this strange misconception that if you pay for something, it will be better, it will do more and it will do everything you want it to. Yea maybe this is true depending on your skill set and how high up you want to roll those sleeves. Buy by and large if you are picking good open source projects to buy into (ones that are backed by real companies and not some guy that just codes for fun) more likely then not you are getting the same thing if not more than the paid alternative. RedHat is great for this; take a look at the long list of open source projects they back. These are really amazing pieces of software that they saw real potential in and wanted to help grow….also package up into a branded downstream to make a little money too.

More so then that one of the main reasons I enjoy working with open source software so much is the community. There are tons of people I talk to on a daily basis across the world. We all collaborate on what is going on with the project and how to make it better and we help out strangers as well who hop in and out of IRC only when they need help. All of this collaboration drives innovation and that innovation drives participation. This participation is what makes open source such an art form. I can clone down a repository, write some code, write some tests and submit it for approval to be merged into the official project. By doing this I know have a new feature that I wanted so I can no longer complain that it doesn’t do something I need, while also making it better for whomever else out there might have had the same complaint, or didn’t even know they wanted that feature.

In order to make impactful change through technology, technology must be in tune with the business/end users. If your end users are also technical then what better way to grow your software then to have a community of contributors submitting features they find useful.

 

Documentation: The Lost Art

Overview:

If you have made it this far in your career and have not been lectured on the importance of documentation, told you needed to improve your documentation skills, or that you do not do enough documentation I applaud you. . . seriously, I really do. Documentation is the bane of my existence and the only thing I hate more than doing it is maintaining it. usually get sucked into either going deep into the weeds or glossing over minor details in my documentation; both of which do not help anyone. Today I am going to share with you some tips I have learned over the past couple years on ways to more easily create and maintain documentation.

Documenting Your Code:

Here is the deal, document your code IN YOUR CODE! Do not have external documentation in a wiki or some other thing for code you write. Also do not have full documentation inline.

README Files:

Be very diligent about creating a concise and informative README file. I have found it best to create a generic template and then fill in the blanks. If there are sections that do not apply. . . remove them. All of my README files include the following:

• Table of Contents

• Overview

• Description

• What it Affects

• Requirements

• Usage

• Reference

• Limitations

• Development

• Release Notes/Etc

Not all of those sections are mandatory but it is a nice template to try and follow. If you are not a fan of README files then you can document in your code.

Documenting in the Code:

As I stated above I am not a fan of inline documentation, it is fine for comments and such but is not the place for actual documentation. My preference is a full block of documentation, commented out, before your code even begins. This documentation can follow the same outline as the README file, or be more concise like the example below:

• Description

• Parameter/Variable descriptions

• Requirements

• Release Notes

Your Code, Your Choice:

Whichever one you decide to go with is the right answer, not documenting is the wrong answer. Documenting outside of your code in a wiki or somewhere else technically is not a wrong answer until it comes time to update the docs. I find it far easier to update the docs with a commit/PR that has new features and fixes then to update the code and go somewhere else and update the docs.

Documentation Articles:

When you have to write documentation that does not relate to code you are usually writing a wiki article or using some sort of other shareable tool. I am not going to go into organizing landing pages and tags and all those other features and things you should be doing to make your documentation read like some sort of manual/book. I am going to focus on a single article.

Formatting:

I am going to be brief and blunt here. Nobody likes reading a wall of black text on a white background. It is boring, it does not hold the attention of the reader, and quite frankly it is not fun to do. Formatting can be hard, and time consuming but when all is said and done you have a nice looking page that reads easily and quite honestly you actually feel like you have contributed something worth while. Please take your time and careful consideration when deciding how to format your document because it can be the unknown decision maker if someone thinks what you wrote is useful/accurate or if you half-heartedly threw some words on a page.

Content:

Level of Detail:

Try not to dive deep down into the weeds with your documentation. That level of detail can be discussed in a chat or one-on-one. The goal should be to provide enough detail to get one started and allow them to have enough information to make some decisions that the documentation does not directly address. Every unique scenario or option should not be vital to your documentation. Think more along the lines of quick start guides. You can add more detail than your typical quick start but remember, too much detail and too lengthy you will lose readers.

Videos and Screenshots:

Both are great in theory; both get out of date very quickly. Unless you plan on being diligent about keeping these visuals up to date stick to well formatted wordings. . . is that a word?

If you are creating detailed documentation for something specific then these visuals might be a better fit and change less frequently.

Editing and Review:

Do not review your own documentation. It is likely you will not realize you have skipped important n00b information or have gone off the rails technical. Have someone with less knowledge than you do your review. See if they find it confusing or constructive. Ask them if they feel anything was left out. These people are your greatest resource. . . use them.

Conclusion:

That is my spiel. I hope it helps and I hope I kept your attention. Just remember your primary goal is to give people a starting point and keep them curious. If you can keep their interest peaked they will return and learn more.

Remember you commit code changes frequently with every change completion; document frequently when things change as well. You will definitely avoid those Friday marathon session.

Fostering a Review Culture

Overview

Review culture is often something that is overlooked and you do not realize how
important it is usually until it is too late. Most projects and companies fall
into the trap of encouraging users, developers, admins and anyone else capable to
contribute to their code base by either submitting feature/bug requests and code
for patches or something that does not exist yet. This is a great start and is
most definitely necessary to be successful. However when it comes to promoting
these patches and code contributions from development to productions is when you
find that nobody ever said anything about code reviews. Code reviews might be
the most important part of contributing to something and is definitely the most
overlooked. I know some people will say automated deployments with CI/CD tools
and writing tests etc will negate the need for code reviews, but the reality is
a fully automated pipeline with no human intervention from local development to
production is a pipe dream for most. So what is your contingency plan?

Reviewing Code – Who, What. . . Why?

From my experience in most organizations there is an incorrect perception of
code reviews. Everyone seems to agree that they are important, however very few
tend to agree on what exactly you are reviewing and who exactly needs to review.
My goal here is to try and simplify this a bit and even though there really is
no right answer, maybe my opinions can guide you in a direction.

Who Reviews Code

It almost always seems that the perception is you need to know how to code in
order to review code. This perception in my opinion is incorrect and one of the
main reasons a strong review culture is hard to adopt. Code review is about more
than just knowing the code and that it executes correctly; it is how you learn. You can
gain a deeper understanding of how things work just by reviewing a pull request
without having any prior knowledge. The questions you will have will lead you
down a path of inquiry where you will hopefully continue to learn more.
I guess the short answer to who should review code is anyone and everyone who
wants to contribute. Those that know how to code can review based on
functionality from a technical standpoint while others can review based on
structure and other standards you have put in place. For those that want to make
the jump into doing more technical code reviews a “mentor program” can be put
in place. Pair an inexperienced reviewer with someone who knows the ropes. Let
them benefit from each others knowledge and perspectives. Before you know it
you will have more people capable of doing code reviews than you ever thought
you would need.

What to Review

The easy answer here is to review everything, in detail and be nit picky over
everything. The better answer is to figure out what your automated tests will be
checking for and then fill in the gaps with human code reviews. Code
functionality is usually the top priority for automated testing so it should not
necessarily be the most important part of your human code review. What you
should focus on is more of the structure and syntax of what you are reviewing.
Ensuring there is a style guide that is being followed and that things like
commit messages and documentation meets a standard. You most definitely have the
right to reject a pull request, or at least push back, if it does not conform to
the style guide you put forth and especially if the commit message does not meet
your standards. Many people thing documentation is a no brainer but you would be
surprised how often there is little to no documentation. This is where I am most
stringent because I want people to be able to read a doc and understand what the
code is meant to do, what requirements it has and what dependencies it has in
order to function.

Results

If you put the time in and foster a culture of code reviews and good practices
you will be pleasantly surprised with what your code base ends up looking like.
You need to start at the beginning though. Define standards for commit messages,
documentation, structure etc. Make these well known and documented and then
start enforcing them. Enforce them in the lowest environments possible so it is
known what to expect when going to production. The cleaner your code base and
the more structured it is the easier it will be to find issues and recover.