Our team needs to automate many routine tasks. Can we use a single tool or do we need to use multiple ones?

Question

Our tech comm team has a wide variety of time-consuming, repetitive tasks they we need to automate. We are mainly using Sphinx, reStructuredText, Adobe Illustrator, and Visio.

Specific things we need to automate and make accessible via either a GUI or the command line are:

• Creating reSructuredText files and their associated index entries in the :toctree: with a set of parameters that the author can specify that will be used to fill in fields such as the :ref: name, Title of the page, file name, index tags, and location of the page within the navigation hierarchy.
• Moving sections of the documentation to a new position in the TOC.
• Opening a Visio and/or Illustrator template and linking it appropriately in the .rst file with a specified directive, such as a figure or image with the correct width/height dimensions and caption.

We wish to keep the tooling to a minimum. It must be a solution that can be taught to the entire team who mostly don't have programming backgrounds, but are willing to learn.

Would a macro-type program such as Automator (we are using Macs) be most appropriate? Would we need to consider a programming language? Again, we would like to choose a single technology/tool, not multiple ones.

Answer 1

Automate the Boring Stuff with Python by Al Sweigart. This is hands down the best single resource to learn how to do exactly what you are asking for. It's a book about programming for people who are not programmers, and it focuses on automating the repetitive tasks cubicle workers meet during their workday. You can read it online for free, or pick up a copy from Amazon or No Starch Press (links to purchase the book are on the site).

Answer 2

To automate any data manipulation task you need two things:

• Access to the metadata or pattern in the source data that you want to act on.
• The ability to change the metadata or data of the source in such a way that you don't corrupt the file or make it unreadable.

The reason that so many systems that want to permit high levels of automation use XML as a file format is that the XML format is designed to facilitate these two operations. (For example, the fact that an XML does not use pointers or fixed-sized structures means you can update its content without having to update other data in the file.)

There are also many good well-tested tools for manipulating XML, both for accessing metadata and patterns in the file and for updating the files without corrupting them.

Since you have a system with multiple file formats you want to automate, you either need a tool that can access and manipulate all of those file formats, or you need multiple tools.

Most programming languages, of course, will allow you to access or update just about any file, but, outside of libraries for addressing specific formats, they also leave it entirely up to you to decipher how to read and write those file formats and that can be very non-trivial. Python is a great choice if you go this route, but consider that unless you can find libraries for manipulating all the file formats you use, it is going to be a lot of work to get your automation working reliably, and that an update in any of the file formats involved could break it.

So, the answer is that you probably need various tools. But then, of course, you run into the issue that you have to integrate the running and the exchange of information between those tools.

What all this says is that if you want a high level of automation, your best route may not be to go looking for tools to automate tasks on all the formats you use now, but to go looking for a format or formats that already have great automation features or that were designed to be easy to manipulate. And that search is probably (though not certainly) going to lead you to XML.