use Ansible as my personal notebook for documenting coding procedures—both the

ones I use often and the ones I rarely use. This process facilitates my work and
reduces the time it takes to do repetitive tasks, the ones where specific commands
in a certain sequence are executed to accomplish a specific result.

By documenting with Ansible, I don't need to memorize all the parameters for each
command or all the steps involved with a specific procedure, and it's easy to share
the details with my teammates.

Traditional approaches for documentation, like wikis or shared drives, are useful
for general documents, but inevitably they become outdated and can't keep pace with
the rapid changes in infrastructure and environments. For specific procedures, it's
better to document directly into the code using a tool like Ansible.
Ansible's advantages

Before we begin, let's recap some basic Ansible concepts: a playbook is a high-
level organization of procedures using plays; plays are specific procedures for a
group of hosts; tasks are specific actions, modules are units of code, and
inventory is a list of managed nodes.

Ansible's great advantage is that the documentation is the playbook itself, so it

evolves with and is contained inside the code. This is not only useful; it's also
practical because, more than just documenting solutions with Ansible, you're also
coding a playbook that permits you to write your procedures and commands, reproduce
them, and automate them. This way, you can look back in six months and be able to
quickly understand and execute them again.

It's true that this way of resolving problems could take more time at first, but it
will definitely save a lot of time in the long term. By being courageous and
disciplined to adopt these new habits, you will improve your skills in each
iteration.

Following are some other important elements and support tools that will facilitate
your process.
Use source code control

"First do it, then do it right, then do it better." —Addy Osmani

When working with Ansible playbooks, it's very important to implement a playbook-
as-code strategy. A good way to accomplish this is to use a source code control
repository that will permit to you start with a simple solution and iterate to
improve it.

A source code control repository provides many advantages as you collaborate with
other developers, restore previous versions, and back up your work. But in creating
documentation, its main advantages are that you get traceability about what are you
doing and can iterate around small changes to improve your work.

The most popular source control system is Git, but there are others like
Subversion, Bazaar, BitKeeper, and Mercurial.
Keep idempotency in mind

In infrastructure automation, idempotency means to reach a specific end state that

remains the same, no matter how many times the process is executed. So when you are
preparing to automate your procedures, keep the desired result in mind and write
scripts and commands that will achieve them consistently.

This concept exists in most Ansible modules because after you specify the desired
final state, Ansible will accomplish it. For instance, there are modules for
creating filesystems, modifying iptables, and managing cron entries. All of these
modules are idempotent by default, so you should give them preference.

If you are using some of the lower-level modules, like command or shell, or
developing your own modules, be careful to write code that will be idempotent and
safe to repeat many times to get the same result.

The idempotency concept is important when you prepare procedures for automation
because it permits you to evaluate several scenarios and incorporate the ones that
will make your code safer and create an abstraction level that points to the
desired result.