Author Archives: miriamannelevy
Hart-Davidson hits the nail on the head, Content Management Systems (CMS) “do not do that work by themselves” (p. 14). A CMS can give a company what they are willing to put into it. They are not a solution, they are a tool. They are exactly what we make of it. Hart-Davidson states that “technical communicators typically come to play many different roles and deploy diverse sets of skills over the course of a career” when using CMS (p. 134). The roles mentioned must be assumed, but to successfully integrate the CMS into the company, the company must also integrate one or more company processes into the system to really benefit from it.
Training or some kind of education on how the company uses a CMS is a key to success. I’ve used quite a few systems and have seen excellent and poor uses of them in companies. When companies don’t have any rules around how a CMS is used, it becomes a free-for-all of good and bad information. It’s confusing. There is a plethora of online content available online for learning how to use and manage CMS systems online. However, even if you know how to use the system, this may not be how the company uses it. The video below only touches on some common mistakes in administrating SharePoint itself and it’s over an hour long.
Michael J. Salvo and Paula Rosinski both discuss “mapping” and “signposting” in information design (pp. 112-114). These concepts are a big part of UX and extremely important to ensure users can become literate in a system. I’ve found these levels of user interface designs are not well applied to most CMS. At one of the companies I worked for I had to redesign the front-end of a SharePoint site to make it more accessible and simplified for others in the company. This tells me that we have a long way to go in our design of CMS from a design perspective. Confusion in using the interface itself will almost surely create inconsistent data, especially when most people will have access to the system.
Process in how you use a CMS is key to making the system useful. Yes, it can allow versioning of documents, but when people are not required to update or sign off on documentation, it can create data that looks trustworthy but is not. Most systems have workflows integrated into them, but unless going through that workflow is a part of a sign off process for the deployment of a product, then why would people go through the hassle?
To make sure our documentation is trustworthy, my team and I will link our documents to specific releases of software. This way it will be clearer in what context you can assume a document may be relevant for. In terms of metadata we make sure that everything is under our team’s section in the system. We also have the option to tag certain customers if the document is specifically relevant to that context. The process we employ around this ensures that we do not have to continually maintain every document, but instead deploy documentation at our own pace and as needed.
I don’t think I could live without a CMS at a company these days, because the alternatives are much worse. But literacy in these systems remains a problem. This is probably due to the fact that the users are not the same as the customer. Additionally, I see many systems treated as a golden solution instead of a platform. It will be interesting to see how these systems and their usages evolve over time.
I found this week’s reading fairly awkward as it included software engineers as technical communicators. Software Engineer is a very misused term to begin with. Rachel Spilka’s book gave me the feeling that they used to be more document centric, but now they are more jack-of-all trades developers and managers, sometimes dev ops, and sometimes just programmers. A lot of software industry titles trend towards a jack-of-all trades type of job, hence the new title “Full-Stack engineer”. Full-stack engineers are usually developers who know all aspects of how to build a web application. Why pay multiple people when you can get just one that knows how to do everything? Initially, a technical communicator sounded like a far fetch in the software engineer’s knowledge tool-box.
When I was studying for my computer science degree, most professors seemed to verbally accept the fact that most of us were just not going to be gifted in the writing department. It was not a required or emphasized aspect even though I had a software engineering emphasis. In the industry, I cannot disagree with this either. Most legacy code I have worked on is not documented from the technical side at all. It’s not always because of talent or ability, but honestly the last thing most of my colleagues want to do after coding is sit down and write sufficient documentation for days after that. Additionally, one extra line of code has the potential to change most or all of a document on the system functionality. Documentation is looked at by our management as a nice to have, but it’s not a show-stopper if it’s not there. We are never interviewed on our writing skills. This first-hand knowledge made me raise an eyebrow when Spilka listed software engineers as technical communicators from the late 90’s to now.
What I realized part way through reading was that the documentation Rachel Spilka is referring to has changed just like how the job titles have changed. The documentation that a software engineer will generate is kind of dynamic and is not always a formal breed of documentation. Spilka states a couple times in the book that the job of technical communicators has changed audiences, that they have changed from being experts to novice. It seems to me that the responsibility for creating power user documentation has been assumed primarily by software engineers, architects and system engineers, while technical writers create more customer-facing or public documentation.
So, how do software engineers document? We document when we want to ensure that we don’t have to work more than we want. The documentation that we do produce is aimed at fellow engineers so we don’t have to repeat ourselves too much when new people are hired or start working on what we have already built. We also document for production systems for installation and troubleshooting guides for when things go very wrong. Both of these types of documents we call “playbooks” for our engineering sector. These playbooks seem very similar to the initial documentation that was created by technical communicators in the 70’s (Spilka, R., ed., 2010, 22).
We keep these playbooks on a content management system that is accessible by the entire company, so if they want they can just go to our page and try to find the answer to their question before talking to us. We can also receive comments on the content management system so that all discussions on the documentation are public. Sometimes the documentation just looks like notes and sometimes it looks like a proper installation document depending on its purpose. We also document even less formally by creating static and dynamic charts and graphs for the design of our system. These can be the most useful in explaining functionality to other software engineers. We also document by putting comments in code to explain exactly what we are trying to do algorithmically. All of these forms of documentation fully take advantage of the technological changes that have been granted to us to make technical communication more efficient.
This book was written in 2010 so I feel like a revision could occur to navigate even more technical communication responsibilities in businesses today. For example, System Engineers have a huge role in technical communication between all components of a technical product. I feel like this specific role could be very helpful in identifying where some of the technical communication responsibilities have been dispersed in today’s world. Spilka does mention that the content would probably be irrelevant for the types of companies that I work at. Additionally, every company is vastly different in how they incorporate technical platforms and integrate with engineering processes. I can only imagine the challenges Spilka encountered in trying to compile the history of technical communication.
All three readings this week seemed to focus on the ways that the world has adapted to social media and services. In the workplace, our education system, and our personal lives, we have changed how we interact and communicate with each other. There are also new opportunities that social media and services can give us that we have no fully explored yet. This leads to the question; how can we fully take advantage of these new opportunities when we do not fully understand how much or little limitations we have? I will explore aspects of success and failure with both education and work-related adaptations to online services and social media.
The classroom is no longer limited to school hours or physical boundaries. Online classes and academic services used by schools are helping education reach and accommodate more students. Ferro et al. argues that education has expanded to be more inclusive and participatory. Students do not have to wait until class starts, as online resources can help them keep in close communication. Online forums for classes have always been helpful for commonly asked questions by students to help everyone involved in the class more efficiently share knowledge and misunderstandings in coursework.
I cannot argue that using online services for school isn’t helpful, but I do feel like it has a long way to go. With the budget limitations every education system has, it is difficult to quickly improve and create a more efficient online educational environment. I am currently enrolled in two Universities and taking online courses with both. The other University I am getting my Master’s degree in computer science. Compared to my bachelors which was all in person, this experience has been much more of an independent journey. Half of the fun of college was meeting people and talking to them about literally anything but school. I do think that online courses can be improved in relation to this. For example, what if we were provided with, encouraged, or expected to use an active communication service, like a chat service, to get to know each other and collaborate with better. Forums and email give us passive communication, and this can lead to students and teachers only discussing what they need to get work completed. It feels much less likely we will actually get to know small details about each other when we have our real lives offline. Longo states that community can be as much “an act of exclusion as it is an inclusion” (p. 5). It seems as though the online classroom has created a community that is more academic than social.
When reading Pigg’s article about distributed work I was quite surprised in the direction that was taken. I thought it would focus on a company like mine with offshore workers, but instead it was much simpler. The study on Dave and his fatherhood blog was completely inspiring. I was very impressed by his ability to establish a niche community in a boundary-less environment of the internet. I love that the internet gives a voice to people like this. In the book industry, you may have the best idea, but getting published is still chalked up to luck. Now we have this uncharted opportunity to be both a writer and an entrepreneur. Being successful may still have to do with luck, but getting your work into a public domain is trivial.
Pigg also brings up room for improvement in the work environment especially when considering employees restrictions involving “cyberslacking” and internet monitoring. Although it may be obvious that certain websites may be inappropriate for work, the nature of my job relies heavily on access to multiple services and social media sites. One example is that we have Skype and most chat options blocked on our internal network. Half of my team members live in Maryland whom I have to call daily, so we end up creatively huddling around phones and sharing web communication tool accounts just to do our jobs. Additionally, integration with certain social media sites can be required depending on the projects we are working on. To do this we have to ask special permission from IT to do jobs assigned to us. Ferro et al. explores the expanding usage of social media and online services that people use to complete their jobs today. It looks as though we will need to reevaluate our approach and the tradeoffs of restrictions vs. employee efficiency.
Both work and education have gone through a lot of trial and error in order to adapt and take advantage of online technologies. Although there seem to be a lot of potential innovations, these aspects of our lives have budgetary limitations that cannot afford error. At the rate technology is changing these parts of our lives may never fully embrace the newest capabilities available, but they are definitely opening up new opportunities.