Visit the project site at via-it.wiki. To log in, click the link in the top-right of the window. Then enter username Guest with password VIAguest2022$
The Gig
VIA Information Tools develops Manufacturing Execution System (MES) software. You can learn more about VIA’s software at the this case study’s page, which examines my design of graphical educational content that teaches VIA’s software.
As a technical writer for VIA, I had two early editing priorities: the software training guides and in-app documentation.
The training guides are used as lesson materials for in-person training sessions. The PDFs total about 500 pages between 13 separate sections; there’s lots of exposition in the guides, but also screenshots and exercises. If read linearly, they progress from high to low levels of abstraction, beginning with basic MES concepts and shopfloor user training, and ending with process programming techniques.
VIA’s software works by arranging pre-defined blocks of code into sequences. Each block, called an atom, represents a discrete manufacturing step, and atoms are arranged into sequences that represent complete manufacturing operations. There are over 600 different atoms, and each one has an entry in the in-app documentation. Each entry progresses from high to low levels of abstraction, too, beginning with a practical explanation of the atom—that is, what work the atom does—, and ending with a description of the atoms’ back end—database operations, variable assignments, and so forth.
The Snag
I spent my first weeks at VIA reading the training guides in Google Docs, since it was the best way to learn the software. I proofread the documents along the way, too.
As I read the manuals, I hit the same snag over and over. While reading about one topic, I’d need to refer to a different topic in an earlier guide. I read the guides in linear order, but my knowledge gaps were random. I’d have to jump around a lot—not only within a single document, but from one document to another—to track down some specific factoid that would plug a gap. It significantly slowed my mastery of the software.
I’d also have to refer to the training manuals while editing the atom documentation. The guides feature programming examples for common manufacturing processes: how to set up a model for production, how to marry two parts together, how to program a verification scan, and so on. Each process is represented by a specific sequence of atoms—like composing a sentence from words. To competently edit the atom entries, then, I had to understand the programmatic contexts in which they were used. I had to understand how to use atoms “grammatically correctly.”
Another thing about the atom documentation is that it’s stored in a database table in the software. Entries are updated in the software’s development version with a tool that performs SQL commands on the documentation table. So there wasn’t a good platform for simply working on atom entries: the SQL tool was not a word processor.
So I jumped back and forth between two distinct information streams: the training manuals and the atom entries. The manuals were long, linear and bounded by Google Drive’s navigation and search limitations. The atom entries were isolated in a database, which I could read in-app, but had to edit with a separate tool. There was no common denominator that connected the information between the atom documentation and the training guides.
The Wiki
Once I understood the limitations of my information ecosystem, I realized how beneficial a wiki could be as a documentation hub. The advantages were numerous. Transferring VIA’s documentation to a wiki would accomplish the following:
Simplify the drafting process of atom documentation. Users could collaborate through the wiki, and edits could be saved and reviewed before being uploaded to the documentation database.
Consolidate multiple information streams under one domain, in a platform that features powerful search and link functionality.
Provide a scalable, web-based platform for generating documentation and developing a user community.
I chose Mediawiki software to run the wiki. It’s versatile, free, and has a strong support community. Wikipedia runs on Mediawiki, so anyone who has used Wikipedia would immediately know how to use the documentation wiki.
I served the site on a Google Cloud micro machine. There wouldn’t be much traffic to the site while I laid its groundwork, so a small machine would do, and the server could be scaled up as needed.
Design Considerations
The site’s layout is like many wikis: simple and easily navigable, especially out of the home page. I designed the wiki to be deep, rather than broad. The main page is the nexus: from there it only takes two or three clicks to get to any other page on the site. The home page’s web copy, written in bold, advises users in a light but direct tone about the most important parts of the site. A visitor can read the entirety of the page’s copy in a short time, enabling speedy navigation.
The main page steers users towards one of three category pages: the atom dictionary, the map directory, and the programming encyclopedia. Users navigate the site according to their knowledge gap. These three pages are also linked in the left-hand sidebar menu.
The atom dictionary comprises the in-app atom documentation stored in the software’s database.
The map directory lists predefined maps (i.e., sequences of atoms) that represent common manufacturing processes. The directory addresses a programmer’s need to quickly deploy process solutions to the shop floor. The maps in the directory were sourced from training guides and VIA staff.
The programming encyclopedia lists programming-related pages by topic. Many of the pages in the encyclopedia are sourced from the training guides; some pages feature reference materials that are helpful with the software.
Above: the wiki’s home page.
Atom Dictionary
The wiki was immediately useful for editing atom documentation. While developing the wiki as a larger knowledge hub was a long-term goal, the wiki would take a lot of work to eclipse the training guides in terms of practicality. So much of my early effort in developing the wiki was spent on creating the atom dictionary, and then using the dictionary to edit entries.
The wiki features systems that encourage high-quality and organized contributions from users. Editing is managed with a graphical semaphore system that directs the flow of work between contributors. Atom entries with “red lights” require editing, “yellow lights” are in the process of editing, and “green lights” are ready for upload to the database. The graphics are added to a page’s code with a code template; pages can be sorted by their editing status according to which pages feature the templates. Examples are below:
The video at right provides a glimpse of the atom dictionary’s main page →
Map Directory, Programming Encyclopedia, and the Rest
I continued to develop the map directory and programming encyclopedia on an ad hoc basis. I added maps and articles here and there if they helped with my atom documentation editing, which was the immediate—and a very substantial—priority. As such, there is not a tremendous amount of content in the map directory and programming encyclopedia, but the structure is there.
A few other pages are linked from the home page: site admin (covering topics from security to back-up protocols), a how-to guide for contributing to the wiki, and software release notes.
In Conclusion
As a technical writer, developing a wiki was a boon for my productivity and mastery of VIA’s MES software. Mediawiki was a great choice for a variety of reasons. The wiki features:
Enhanced link and search functionality for quicker mastery when researching and quicker editing when contributing.
Normal website functionality: pages can be bookmarked and opened with new windows (which could not be easily accomplished with training manuals PDFs, and was impossible with in-app documentation).
A platform for storing documentation and collaborating (which did not exist before).
The flexibility for further development of documentation, trainings and a user community.