3

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.

migrated from techcomm.stackexchange.com Feb 20 '18 at 15:17

  • 2
    This doesn't seem like a question about the subject of Technical Communication in the context of this site. The fact that you just happen to be engaged in a technical writing is merely coincidental to the actual subject of this post. We have to remain a bit guarded against this becoming a general computing site. – Robert Cartaino Jan 28 '18 at 17:36
  • 1
    There's a lot of keyboard macro tools that let you do less intelligent but nevertheless tedious automation. I like AutoHotKeys. – ForEachLoop Jan 29 '18 at 1:58
  • 3
    I'll try to put a techcomm spin on this :) I've created a VBA script that does some basic editing tasks on Word documents (I call it the "Editor's Eye"). It goes through a doc and flags or changes a set list of known issues (capitalization, word choice, spelling, etc.). It saved me (and my non-native-English-speaking engineer writers) a lot of time. If you are interested in seeing the code, PM me. – Yoel Jan 29 '18 at 10:11
  • 1
    @Amruta2799: I agree it is a vital asset to tech comm teams who often don't have any proficiency in programming. I will try to give a more domain-specific question. – David Vogel Jan 30 '18 at 16:08
  • 3
    I think that this should be re-opened because, with the edits, it's about tools commonly used in technical writing. – EJoshuaS Feb 1 '18 at 17:21
3

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).

  • 1
    Fantastic resource! I've been putting this to use and it is just the tool we need. Extremely flexible, yet accessible to our team. – David Vogel Feb 10 '18 at 20:47
1

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.