Tools Productivity

1903 - a pivotal moment in history.

The last 120+ years have ahd a lot of pivotal moments, of course - and perhaps 1903 doesn’t stick out in your mind the way, say, 1914, 1939, or 2001 does.

Nevertheless, 1903 was important - and perhaps the most memorable reason why comprised just 0.00028% of that time.

That’s how long the Wright Brothers’ spent in the air that year.

Their first powered, sustained, and controlled flight was a pivotal moment in history. It marked the beginning of a new era - one of transportation, one of innovation. Bad things, too: aerial bombings - but that was still far in the future.

Interestingly, people often focus on the brothers overcoming long odds - they possesed willingness to continue when others might have failed.

Fearlessness alone, though, wouldn’t get the job done - the brothers’ also had meticulous data collection and analysis.

They conducted extensive experiments, recorded detailed notes, and iterated on their designs based on the data they collected. They understood that to achieve their dream of flight, they needed to have a deep understanding of the forces at play and how to control them.

That’s a good example for us today - whether you’re at a small tech startup or a giant enterprise, blending innovation with careful analysis can benefit you immensely.

However, our situation is not that found by the Wright brothers in 1903. There are important differences.

Today, we have more tools than the Wrights’ did - but as everyone has access to many of those tools, they become, not an advantage, but simply a disadvantage to those who don’t have access or don’t use them effectively.

Vendors know this. They often make decisions based, not on what is best for the customer, but what is best for the enterprise. At times, this may not be a severe problem; but at other times, it can be extremely vexing, such as when a critical functionality is removed or a critical software package discontinued. The more your company relies on a tool, the more vulnerable you are to the whims of the vendor.

Indeed, virtually rely on ticketing systems like Asana to manage our projects and collaborate with our teams. But like the Wright Brothers’ early flying machines, these tools sometimes crash - and like early airlines, they go out of business.

Data Silos and “Good Enough”

Asana, like many SaaS tools, stores your data in its own proprietary format - locked away in the cloud. While this is a common practice, it can make it difficult to use your data outside of Asana. The export options provided by Asana are limited and may not include all the data you need. Further, if you have many projects, it may become quite cumbersome to regularly export and re-import your data to another program.

This can lead to data silos and vendor lock-in. If your data is trapped in Asana’s format, you may be forced to continue using the tool even if it no longer meets your needs, simply because migrating your data would be too difficult. This lack of data portability can be a significant problem, especially for long-term projects or if you need to integrate your data with other systems. Indeed, many people stay wedded to a particular tool simply because it is “good enough.”

As Thomas Edison once said, “Many of life’s failures are people who did not realize how close they were to success when they gave up.” Don’t let proprietary data formats hold you back from achieving your goals. Ask yourself, are you confident that your tool is helping, rather than hurting, you? Do people use the tool as little as possible, or do they enjoy using the tool?

The Power of Plain Text

This is where the power of plain text shines. Plain text data, like YAML, is like a physical printed book. It can be read by anyone who understands the language, without needing any special tools. It will still be readable decades or even centuries from now, long after current software has become obsolete.

Syncing your Asana data to YAML gives other benefits, too - easy adhoc analysis and improving custom tools.

Here’s a simple example of what an Asana task might look like when exported to YAML:

---
id: '1200694331183094'
path: 
  - 1200694331045602
  - 1200694331046858
name: Research data export options
notes: |
  We need to find a way to regularly export our Asana data in a format that's easy to use outside of Asana. 
  
  Key requirements:
  - Human-readable format
  - Includes all relevant task data
  - Easy to version control
  - Can be automated to run regularly  

completed: false
assignee: James Smith

As you can see, the YAML format provides a clear, structured representation of the task’s fields and values. It’s readable by humans and can be parsed by virtually any programming language.

The exported YAML data opens up a world of possibilities. Regular exports ensure you always have a backup of your Asana data. You can store these backups in multiple locations for added safety. If you decide to move away from Asana, having your data in a standard format like YAML makes the migration process much easier.

With your data in a plain text format, you can use a wide variety of tools to analyze it. You could look for patterns in task completion times, measure project progress over time, or generate custom reports. Having your data in a format that’s easy to parse makes it possible to build custom integrations and automations. For example, you could write a script that automatically creates tasks in another system based on certain conditions in your Asana data.

Charles Babbage, the father of the computer, envisioned a machine that could be programmed to perform any calculation. Today, we often focus on speed - and, indeed, early computers were faster than hand calcuations, but by nearly the margin as today. The flexibility, though, of Babbage’s Analytical Engine and it’s descendents is no small factor - but we often lose the full advantage of such flexibility to vendor lockin. Exporting your project management data not only gives you safety, but also possibilities for custom analysis and automation using AI, spreadsheets, custom scripts, or any other tool you may imagine.

Getting Started with House of YAML for Asana

Alexander Graham Bell, the inventor of the telephone, famously said, “Before anything else, preparation is the key to success.” This principle applies well to setting up House of YAML for the first time.

1. Make sure you have Ruby installed on your system. House of YAML is a Ruby gem, so you’ll need Ruby to use it. I recommend against using system packages, such as those provided by apt-get or brew; instead, use rbenv or mise to install them.

2. Install the house_of_yaml gem:

   gem install house_of_yaml
   

3. Configure the gem with your Asana API key. You can find this in your Asana account settings:

   require 'house_of_yaml'
   
   HouseOfYaml::Services::Base.add 'asana', asana_api_key: 'your_asana_api_key'
   

4. Choose a location for your exported YAML files. This should be a directory managed by Git. Initialize a new Git repository there if one doesn’t already exist:

   mkdir asana-data
   cd asana-data
   git init
   

5. Create a Ruby script (e.g., export_asana.rb) with the following content:

   require 'house_of_yaml'
   
   repo_path = '/path/to/your/repo'
   HouseOfYaml.sync(repo_path)
   

6. Run the script:

   ruby export_asana.rb
   

7. Commit and push the exported files to a remote Git repository:

   git add .
   git commit -m "Initial Asana data export"
   git remote add origin https://github.com/your-username/your-repo.git
   git push -u origin main
   

8. Consider setting up a regular task (e.g., a cron job or a GitHub Action) to run the export script periodically. This will ensure that your exported data stays up to date.

Conclusion

The Wright Brothers achieved the first powered, sustained and controlled airplane flight in 1903. This milestone was made possible by their relentless experimentation, data collection, and iteration. In the age of SaaS, taking control of your data through tools like House of YAML is a similar kind of empowerment that opens up new possibilities.

By regularly exporting your Asana tasks as YAML files using House of YAML, you ensure that your data remains accessible, portable, and under your control. Storing these files in a Git repository adds the benefits of version control, backup, and collaboration.

Whether you’re looking to migrate to another tool, analyze your data in new ways, or build custom integrations, House of YAML provides a solid foundation. It’s like having a personal assistant that keeps your data in order, always ready for you to use it in new and innovative ways.

So take control of your data today. Install House of YAML, set up a regular export, and start exploring the possibilities. And while you’re at it, consider contributing back to the project. Like the Wright Brothers’ first flight, your contributions could help others soar to new heights.

Alternatively, if you’re not in the mood to customize your Asana installation, why not contact us? We’ll set you up with custom integration scripts - anything you can imagine, we can do it.

“The increase of this efficiency is essentially the problem of the manager, and the amount to which it can be increased by proper study is, in most cases, so great as to be almost incredible.”

So said Henry Gantt.

He wasn’t wrong.

In 1910, he developed the Gantt chart - a revolutionary way to visualize project schedules. His work helped oversee massive projects, including the construction of the Hoover Dam and the Interstate Highway System. Eventually, it lead to modern project management.

In time, things change. Over a century later, we’ve traded in paper charts for powerful digital tools… but one advantage that paper charts have is distinct lack of lock-in. If you learn to work using paper, you can work with any brand - you don’t need to retrain to switch brands of notebook.

Indeed, can you imagine a world where changing paper vendors required reformatting all your paper records?

That’s a silly thought, of course - but that’s the situation we find ourselves with project management software today.

That’s where House of YAML comes in.

For many teams, project management tools have become essential - they help you keeping teams organized and on track. Take JIRA, for example; for software teams, you can use it track tasks, bugs, and features. You can use it to manage many other types of projects as well.

However, relying on a single tool or a single vendor for all your project data can be risky. What happens if you need to move your data out of Jira? Maybe your team is switching to a different tool, or perhaps you simply want a backup of your data in a more portable format. That’s where House of YAML comes in.

The Problem with Proprietary Data Formats

Many productivity tools, including Jira, store your data in their own proprietary formats. You can often export a slice of the data easily, but there isn’t much incentive for vendors to create easy transition paths - which can effectively create a “data silo” that makes it difficult to use your data outside of that specific tool. This is a serious problem for many reasons:

1. Vendor lock-in: If your data is trapped in a proprietary format, you may be forced to continue using that tool even if it no longer meets your needs, simply because migrating your data would be too difficult.

2. Limited data portability: Proprietary formats often make it hard to move your data to other tools or integrate it with other systems. This can limit your flexibility and hinder automation efforts.

3. Reduced data longevity: If the tool you’re using becomes obsolete or the company goes out of business, your data may become inaccessible if it’s in a proprietary format that is no longer supported.

Even if the tool provides an export function, the format may not be ideal for long-term storage or for importing into other systems. CSV exports, for example, can lose important structural information about your data.

The Power of Plain Text

In contrast to proprietary formats, plain text is a universal and timeless data format. It has several key advantages:

1. Human-readable: Plain text can be read and understood by humans without the need for specialized software. This makes it accessible to anyone, regardless of their technical expertise.

2. Universal compatibility: Virtually every computer system can process plain text. It doesn’t require special software or libraries to parse.

3. Longevity: Plain text has been around since the dawn of computing and is likely to remain relevant for the foreseeable future. By storing your data in plain text, you ensure that it will remain accessible and usable for years to come, regardless of changes in technology.

4. Version control-friendly: Plain text works well with version control systems like Git, which allow you to track changes to your data over time.

By exporting your Jira data to a plain text format like YAML, you can break free from proprietary data silos and ensure the long-term accessibility and portability of your project information.

Enter House of YAML

House of YAML is a powerful Ruby gem that simplifies the process of exporting your Jira tickets (and data from other tools like Asana) as YAML files and storing them in a Git repository.

YAML (YAML Ain’t Markup Language) is a human-friendly data serialization standard that is widely supported across programming languages. It uses indentation and simple punctuation to represent structured data in a way that is easy for humans to read and write.

Here’s a simple example of what a Jira ticket might look like when exported to YAML:

---
id: '1033'
path: '10001'
summary: when you create a duplicate camp shipping rate then you get this error
description: |-
  As a user, I want to be able to search for articles by keyword,
  so that I can find the information I need quickly.

  Acceptance Criteria:
  - Search bar is prominently displayed on article listing page
  - Search returns relevant articles based on title and body content
  - Search results are paginated with 20 results per page  

status: Complete and Tested
assignee:

As you can see, the YAML format allows for a clear, structured representation of the ticket’s fields and values. This format is not only easy for humans to read and understand, but also easy for scripts and programs to parse and process.

Using House of YAML to export your Jira data is straightforward:

1. Install the house_of_yaml gem in your Ruby project.

   gem install house_of_yaml
   

2. Configure the gem with your Jira API credentials. You’ll need to generate an API token in your Jira account settings.

   require 'house_of_yaml'
   
   HouseOfYaml::Services::Base.add 'jira',
     base_uri: 'https://your-jira-domain.atlassian.net',
     email: '[email protected]',
     api_key: 'your_jira_api_key'
   

3. Specify the path where you want to store the exported YAML files. This should be a directory managed by Git.

   repo_path = '/path/to/your/repo'
   

4. Run HouseOfYaml.sync to fetch your Jira tickets and store them as YAML files in the specified Git repository.

   HouseOfYaml.sync(repo_path)  
   

5. Optionally, push the changes to a remote Git repository for backup and sharing.

   git add .
   git commit -m "Export Jira tickets to YAML"
   git push origin main
   

After running this script, you’ll have a directory full of YAML files, each representing a Jira ticket. The files are organized by project and issue ID, making it easy to locate specific tickets.

your_repo/
  PROJECT-A-ID/
    1000.yml
    1001.yml
    ...
  PROJECT-B-ID/
    1001.yml
    1002.yml
    ...  

House of YAML handles all the complexity of interacting with the Jira API, pagination, and error handling, making the export process simple and reliable.

Benefits of Storing Your Data in Git

Storing your exported Jira data in a Git repository amplifies the benefits of using a plain text format like YAML. Git is a distributed version control system that is widely used for managing changes to source code, but it’s equally effective for managing changes to any plain text data.

Here are some of the key benefits of storing your Jira exports in Git:

1. Version control: Git keeps a complete history of changes to your files over time. Every time you export your Jira data, you can commit those changes to Git. This allows you to see exactly what changed between exports, revert to previous versions if needed, and track the evolution of your project data over time.

2. Backup and redundancy: Git repositories can be easily cloned and synchronized across multiple computers and servers. This means you can maintain copies of your exported Jira data in multiple locations (e.g., your local machine, a company server, a cloud hosting service like GitHub). This distributed approach provides a robust backup system for your data. Even if one copy is lost, you can easily restore from another clone of the repository.

3. Collaboration and review: Git is designed for collaboration. Multiple people can work on the same repository of exported data, and changes can be reviewed and merged using Pull Requests. This can be useful if multiple team members need to access and update the exported data, or if you want to have a review process for data changes.

4. Integration with other tools: Because your exported Jira data is in a Git repository, you can easily integrate it with other tools and workflows that support Git. For example, you could set up a continuous integration pipeline that runs automated tests or transformations on your exported data whenever changes are pushed to the repository.

5. Data portability: With your Jira data in a Git repository, you can easily move it to other systems or share it with others. You can push the repository to a remote hosting service like GitHub, or package it as a tarball for distribution. The plain text YAML format ensures that your data will be readable and usable in a wide variety of contexts.

Conclusion

Regularly exporting your Jira tickets (and other project data) as plain text YAML files using House of YAML is a powerful strategy for ensuring the longevity, portability, and accessibility of your data. By storing the exported files in a Git repository, you gain the added benefits of version control, distributed backup, collaboration, and integration with other tools.

At the outset, we spoke of Gantt and his words regarding “increase of this efficiency” - and, as noted, that’s something a vendor can help you with.

But what if the vendor isn’t working for you anymore - instead of increasing your efficiency, they are decreasing it?

Whether you’re looking to switch project management tools, integrate your data with other systems, or simply ensure that your project history remains accessible, House of YAML and Git provide a robust and straightforward solution. Give it a try - and while you are it, submit a PR or three.