My advisor’s book suggests that people rarely think about the quality of the actual writing online. He suggests there are no values or standards or rubrics for assessing text in a cyber world of “place” metaphors.

He has a model named EUPARS that he uses to assess genres of web text.
Exigency: Why is it needed?
Urgency: How bad is it needed?
Purpose: What is it supposed to do?
Audience: Who will read it?
Rhetoric: How does it persuade?
Structure: Does the layout/design afford these considerations?

He wants me to use the model in my own dissertation. Essentially, my dissertation uses North American genre theory to describe how traditional documentation standards don’t meet the needs of contemporary software developers. I can use genre theory to predict the documentation produced by software developers; however, only traditional developers tend to produce the documentation I predict. The contemporary developers don’t meet predictions. That said, I’m looking for documentation by traditional standards; I’m not looking for the “rhetorical forms” that the contemporary developers are forming to meet their own needs. My dissertation uses genre theory to describe how oral communication is an important rhetorical form (eschewed by traditional standards). There are a lot of fragments of communication that are bound together by oral communication, instead of traditional documentation.

The meta-language of genre theory is so important. I’m predicting what rhetorical forms should look like in software development. The industry guides state the rhetorical forms are documents. While I can predict documents in traditional practices, I cannot predict documents in contemporary practices. Rather, I can predict rhetorical forms. The oral communication is the rhetorical form that I find in contemporary software development. Until someone uses a meta-language to predict more than simply documentation, then contemporary developers would continue hammering their heads against a wall trying to meet their industry’s value for structured communication.

So where does my advisor’s EUPARS model come in?

Researchers agree that the three most important values to genre theory are: 1) purpose 2) situation and 3) community. Consequently, a community responds to situations according to different purposes. As the community cycles around and encounters the situation again, the rhetorical forms the community used the last time may or may not work because the community’s purpose may have shifted. The contemporary developers are a community that changed their rhetorical forms to meet new philosophical objectives in their methodology. In other words, the situation changed and they adapted the way they communicated to the new situation. However, they haven’t reassessed the purpose of their rhetorical forms. They are not writers or communicators so they continue to fulfill the purpose of traditional writing standards.

Consequently, my advisor wants me to use his five values instead of the three values I intended to use. That isn’t the problem. The problem is that the EUPARS model is for customer-facing, written communication. What is the exigency of developer chitchat at the water fountain? What is the purpose of an impromptu collaboration at one team member’s computer station? Even more significantly, oral communication has no artifact so there is necessarily no layout/design to assess.

The only thing that works well is if I stick to the documentation and the way my advisor uses his model to compare old contexts to new contexts. In other words, if a designer imports text from the company’s old site to the new site then the designer can use the EUPARS model to compare the contexts and gauge appropriateness. In the same way, I can compare standard documentation in the old context against documentation in the new context. The model will show that the traditional documentation is not appropriate in the new context.

I would have to use his model in tandem with my own model of criteria. I have three chapters where I use my model of criteria to predict the documentation I hoped to find. I have a fourth chapter where I will use my model of criteria to show oral communication is a new rhetorical form. My advisor suggests that I can use his model to show how well rhetorical forms work in each context. The three chapters will demonstrate failure and the fourth chapter should demonstrate success. His model would work to empirical way to describe why it does or does not work. If I think of oral communication as a rhetorical form and EUPARS is designed to assess the quality/appropriateness of rhetorical forms, then I should be able to use oral communication in EUPARS—though, without the syllogistic error.

Jason Cootey, M.S., ABD
Project management and documentation management
Web Portfolio

The biggest challenge is that my advisor recommended I tone down the genre language in my proposal; some of the faculty on my committee have little exposure to North American Genre Theory and wouldn’t understand. We decided my big objective was to articulate my purpose without the theoretical framework. However, at my dissertation proposal defense, the committee members wondered why genre theory was so important if I could describe the problem without the theory. In addition, the committee members wondered what contribution I actually planned to make to the field of professional communication. So I can’t let down on the importance of the theory in articulating my argument; however, I can’t write an impenetrable, theoretical introduction either.

The solution is the grammar of genre theory: Dynamism, Situatedness, Form/Content, Duality of Structure and Community Ownership. These five terms are pillars around which there are more specific grammars. The theory of genre theory gives me a large vocabulary I can use to describe documentation practices. This is actually very important to my dissertation project because traditional documentation standards are couched in traditional language and I would never be able to use that same language to describe something new.

I’m suggesting something very post-structural about software documentation. They can’t describe their problems because their vocabulary is keyed to describe how to meet the traditional standards. I have to get outside the industry guidebook definitions and descriptions. In other words, North American Genre Theory is a meta-language I can use to analyze the language, values and practices that constitute the diverse rhetorical forms of software documentation. My dissertation re-conceptualizes documentation in opposition to traditional values, much like contemporary developers who conceptualize their methods in opposition to traditional methods. Genre Theory lets me step outside the traditional expressions, norms, epistemologies and situated cognition that define software documentation.

I know that oral communication is the solution. Of course, my dissertation seeks to prove that oral communication is the solution but a meta-language empowers me to write about traditional documentation without oral communication, identify oral communication in contemporary documentation and clearly explain how oral communication is supposed work in good documentation practice.

Once I show how oral communication fits back in I can highlight my samples of agile communication. I have sticky notes, scraps of paper, email, etc that are all byproducts of oral communication.

Therefore, while my dissertation’s introduction can’t use an undefined grammer, it can make the case that oral communication is under-examined, under-conceptualized and under-described with traditional knowledge systems. I can promise North American Genre Theory as the meta-language that lets me fill the gap.

This approach is in fact scaled back from the original objective of proving genre theory is missing oral communication or that it can’t describe contemporary development. Like my dissertation committee was trying to say, I cannot take on both genre theory and software documentation at the same time. The important fact is that genre theory can describe contemporary development; in fact, it describes development very well. Developers are a community with new values and their recursive actions have created new needs and new rhetorical forms. I’m simply identifying what those rhetorical forms are—because they are not traditional and cannot be described with traditional language.

The grammar of genre theory is much more comprehensive than I represent with the five pillars. Those five pillars come from the combined research of Carol Berkenkotter and Thomas Huckin; they are not even the luminaries in the field. Carolyn Miller and Clay Spinuzzi both produce research that is key to genre studies. Spinuzzi introduces Genre Ecologies and Miller provides the key definition used by anyone who is anyone. Miller states genres are typified rhetorical responses to recursive situations. The following table is a list of 21 Genre terms that are key to describing software documentation in a contemporary world of development.

Jason Cootey, M.S., ABD
Project management and documentation management
Web Portfolio

inContact

The Technical Documentation Specialist for inContact’s Network Operations team is responsible for writing and maintaining technical documentation as it relates to departmental knowledge bases, product and system support, processes and policies as well network events that may or may not impact end users. The Documentation Specialist will continually innovate to find better ways to deliver outstanding content to our customers and internal team members allowing Network Operations to better serve the needs of our clientele. This position writes a variety of technical articles including but not limited to internal training material, Reason for Outage documents, technical support documentation to serve a wide range of uses and may be responsible for coordinating the display of graphics and the production of the document.

• Collaborate with subject matter experts including but not limited to: Network and Systems Design teams, Network Administration and Production and Production Systems Administration, Network Operations Center, software engineers, quality assurance, trainers, and product management to determine documentation needs.
• Write, edit, index, maintain and revise a variety of online and printed training materials with documentation tools, PPT, and other mediums.
• Prepare technical illustrations, diagrams, and charts.
• Ensure accuracy, completeness, and clarity of documentation materials in conjunction with subject matter experts.
• Research and evaluate new content development tools and methods to improve documentation effectiveness.
• Maintain documentation standards and keep abreast of current information by associating with professional individuals or societies or by reviewing professional publications, newsletters, e-mail, and Web sites.
• Collaborate with Solutions Marketing to ensure documentation materials are available for the Go To Market process.
• Research and document technical information.
• Create training materials for Network Operations support needs.
• Create customer facing notifications during and after network events.
• Create Reason for Outage documentation for internal and external customers.
• Create relevant eLearning courses for new-hires of the Network Operations team.

Company Description

inContact (NASDAQ: SAAS) helps call centers around the globe create profitable customer experiences through its powerful portfolio of cloud-based call center software solutions. The company’s services and solutions enable call centers to operate more efficiently, optimize the cost and quality of every customer interaction, create new pathways to profit and ensure ongoing customer-centric business improvement and growth. To learn more, visit www.inContact.com.

Jason Cootey, M.S., ABD
Project management and documentation management
Web Portfolio

Genre theory describes the generation and maintenance of genres; the theory is not limited to categories of fiction like mystery or science fiction. The theory points out that genres are not eternal truths or innately ontological cosmic forces; in other words, life does not come packaged with genre categories. Rather, genres are constructed relationships between texts connected by sustained human activity.

While writing design documents is a social act that can be described by genre theory, genre theory does not account for the entire act. At least, genre theory does not typically highlight oral communication. Clearly, people talk to each other in social acts; that is why the acts are social. However, I’m suggesting that the writing isn’t the only artifact. I’m suggesting that oral communication is an artifact too, rather than simply background conversation.

The chief reason I have looked to oral communication is because traditional software documentation practices do not fit well in contemporary software development practices. In order to make the traditional documentation fit, professionals straddle two different models at the same time. Professionals can describe documents as important guiding documents in one breath and then describe documents as disposable in the next. While documents are meant to guide projects, transmit design direction and sustain team unity, professional programmers and engineers are not guided by the documents; rather, they use the documents to transmit a record of agreement and implement team contributions up until the deadline.

Documentation is a predevelopment activity; industry authors suggest that the documentation transmits those predevelopment decisions. However, that record of transmission no longer acts as a commanding resource because developers often rewrite the predevelopment documentation. The problem is that development teams do not wish to be tied down to what is written in the documents; they are not guided by the document, they work “on the fly,” and they deploy new ideas up until the deadline. Despite this difference between theory and practice, professionals still write the documentation their way and the documents turn out just fine. The difference between theory and practice is more important than professionals think because either the document commands the project or the professionals command the project. In other words, documents can guide or documents can be disposable tools. While both kinds of documents have their costs, professionals prefer the latter.

Jason Cootey, M.S., ABD
Project management and documentation management
Web Portfolio

Strategy
I like to start with a plan and break tasks down into steps. Once I have steps I am in a better position to gauge the time line. I can also identify the strengths of people who best fit the tasks I have outlined. In this way, I delegate assignments to those best skilled at fulfilling specific responsibilities. I like the steps because it is a great way to evaluate progress, keep contributors engaged and keep meetings focused.

Priorities
Even if the audience is as generic as the NSF, my first priority is audience-driven documentation. For instance, an RFP is full of requirements, described with keywords. Those keywords are the vocabulary of the proposal and the words with which the audience evaluates proposals.

My Expectations
I find that when I clearly outline responsibilities and use weekly meetings for progress accountability then people will innovate and do what it takes to fulfill responsibilities. I don’t like micro-management and I expect initiative; however, I recognize that leadership means actively encouraging and channeling a team’s energy towards a common goal.

Employees’ Expectations
I follow through when I make a commitment. I support and advocate my employees. I model how to resolve problems and complete responsibilities with innovative solutions.

Jason Cootey, M.S., ABD
Project management and documentation management
Web Portfolio

When I went into the interview I was convinced that the documentation was a sufficiently organic that it was an agent in the process of software development. In other words, the documentation had an active role in the organization and evolution of the project. I didn’t know what that looked like but genre theory predicted the document would behave in a very specific way; genre researchers Berkenkotter and Huckin put that behavior this way: “Written communication functions within disciplinary culture to facilitate the multiple social interactions that are instrumental in the production of knowledge.” Not only would documents morph to the needs of the project team but most importantly the project team would rely on the documentation for guidance. The document is a live agent that influences the design of the team, the roles of individuals on the team and the project knowledge of the team. However, I hadn’t experienced anything like that and had no idea what it looked like.

I saw what appeared to be a monumental research problem between the agency of a document in a genre system and the real-life demands of software development practices.

The transmission is what bothers me. If the design document is a vision document that forecasts the final product from the beginning then the document is a guide that must benefit from rapid updates so that the document doesn’t lose the visionary utility. Owens suggested the document was law: “It literally is a law, it’s where we write down the process an then we attempt to follow that process as closely as possible” (personal communication, March 26, 2008). The alternative is that the design document is a record or repository. Developers journal what they have done so that there is a document trail the team can follow when necessary. In this latter case, the developers manage the project’s vision and the design document constrains deviation every time the developer logs progress. In fact, even though Owens suggested the document was a blueprint, he also stated: “we want to make sure our blueprint and our help techs and things like that all kind of match what actually exist…That’s why we do this update specification design artifacts” (personal communication, March 26, 2008). In other words, the team needs to record updates to the blue print to match the project’s ongoing evolution. Consequently, the design document is either an agent in the project community that impacts the project or the design document is a record of the project community that stabilizes recursive development practices.

While genre theory still predicts a dynamic, organic document, Owens’s narrative taught me that documentation was not a process; the documentation was simply a record of the process. Simply put, documentation does not guide teams, influence social interactions or even structure knowledge; rather, documentation is altered to match whatever the team is doing. The cycle of activity organized around governing documents but the documents did not organize the activity. Genre theory either fails to describe the genre of software documentation or the software developers don’t document the right way.

Jason Cootey, M.S., ABD
Project management and documentation management
Web Portfolio

The design document acts as a common, informational reference point for the community of writers, designers, artists, and programmers who act on the reproduction of the documentation. Consequently, the generation, organization and use of that common reference point is critical in coordinating the social activities of software developers.

However, there is a potential problem. Professionals use a more organic document that doesn’t fit the description of a coordinating, guiding document—doesn’t fit the genre criteria purported by the industry guides.

While industry guidebooks advise both students and developers to think of design documentation as orienting documents, they are also clear about the flexibility of the documents. The problem is a flexible document is less orienting and an orienting document is less flexible. While professionals do not have problems negotiating this dichotomy in their information economy, researchers like me seek to learn how to negotiate the difference.

Developers will dispose of documented articulations, rather than be guided by a plan that doesn’t fit the discourse community anymore. Developers labor to produce guiding documents that don’t do any of the guiding. Developers take for granted practice insight missing from the design document instruction available to either professional communication students or professional communicators new to software development.

Duality of structure is a key term for this article; duality of structure describes the design document is a site of stabilizing struggle. In other words, the influence of the document does not come from the text; the influence is from the recursive interaction with the act of transcription, the design document, the community, and the human agents. The effect is a participation that simultaneously constitutes and reproduces the information economy.

The importance of genre theory to my dissertation comes down to 1) describing the social impact of a discourse community on a genre of internal software documentation and 2) the influence of the internal software documentation genre on development practices.

However, genre theory really does not resolve the discrepancy between guidebook recommendations and professional practices.

When I think of what software developers call live, organic, flexible documentation, I think of a very interactive process in which the writing and the programming intertwine closely together. That kind of intertwining process is what I expect to see when I seek to find a model of genre theory. I might try to use genre theory to reconcile the discrepancy but I suspect the same discrepancy is in genre theory. The Duality of Structure seems to simply describe the discrepancy, rather than resolve it. In fact, the original seminar paper uses another theory (paralogic hermeneutic theory) to fill in the gap.

Jason Cootey, M.S., ABD
Project management and documentation management
Web Portfolio

Phase 1: Aristotle’s Assassins

Documentation was supposed to be as described by the industry guides. Yet, it failed the criteria.

Phase 2: Pathways of the West

Documentation met the criteria. We learned later it really didn’t because remote collaboration necessitated documentation that met all the criteria.

Phase 3: Engineering Modules

We set out to replicate the succes of the Pathways if the West project documentation. However, there was no documentation at all. But we still communicated and still produced a successful product. I have tons of samples of the fragments of communication. We still met the criteria because of oral communication.

Phase 4: (Undetermined)

Documentation must be poor or missing. I must learn if oral communication is how they meet the criteria. I have an associate in Logan Utah that manages a very small agile development team; they don’t document and he is willing to let me interview his entire team.

Phase Summary

Phase 1 was the baseline. I started searching everywhere for a model that met my expectations of a software documentation project described by genre theory. I thought I found it with Phase 2. I was excited because phase 2 was what I expected. We conducted phase 3 so that I could observe if it happened again. However, phase 3 did not generate any documentation at all. I thought phase 3 was a bust until we came to oral communication as the solution for why documentation didn’t happen at all in a successful project. I am doing phase 4 to verify that oral communication is the solution after all.

Reflection on Phase Summary

So I ask a few questions in the summary that are very interesting for the development of my dissertation. I think these questions represent intersections or places I haven’t yet elaborated. I think spending time on them will yield significant results.

• What exactly were my expectations as I searched for the model practice?
• How did I plan to observe phase 2 again in phase 3? I need the expectation.
• How did we get to oral communication as the solution? What did it solve?
• Do I want to suggest that the criteria are met because of oral communication? -AND-
• Am I assuming that the criteria are met in the absence of genre?

Attempts to Define the Model of Practice

When developers don’t document well they substitute oral communication for the documentation.

The rhetorical forms of developers’ situations don’t meet genre rules only when “rhetorical forms” is restricted to written communication.

Model of Practice is oral communication that meets the criteria in the stead of documentation.

Developers may or may not document but the oral communication is what sustains contemporary discourse communities.

Software documentation is dynamic, flexible and organic just like genre theory predicts but isn’t for the reasons genre theory gives. First, the contemporary practices use traditional documents that do not match their development model. Second, their documents are not decision-making, meaning-making artifacts.

Possibilities for the Elusive “Model of Practice” Criteria

First set from: (Schultz, Bryant, & Langdell, 2005)

Everyone comes for understanding of details (pp. 398, 399)

Takes shape over time (pp. 398, 399)

General knowledge of project from beginning (pp. 398, 399) [end of preproduction p. 91]

Order of sections is arbitrary (pp. 398, 399)

Exhaustively details everything (p. 91)

Everyone on team has easy access (p. 92)

Second set from: (Adams & Rollings, 2007)

Transmit design to other team members (p. 62)

Record decisions made—paper trail (p. 62) [implies oral communication]

Vague idea of explicit plan (p. 62)

Each member of team has a different idea of what to do so doc solves that (p. 62)

Third set from: (Berkun, 2005)

Reapply same reasoning that created the vision (p. 82)

Document a living thing if questioned and used to justify change (p. 82)

Continual source of motivation and clarity (p. 82)

Major changes should be rare and must be justified (p. 82)

Derive goals from document (p. 83)

Keep it alive and relevant by questions about utility to daily decisions (p. 82)

Adams, E., & Rollings, A. (2007). Fundamentals of Game Design. Upper Saddle River, NJ: Pearson Prentice Hall.

Berkun, S. (2005). The art of project management. Sebastopol, CA: O’Reilly.

Schultz, C., Bryant, R., & Langdell, T. (2005). Game Testing All in One. Boston: Thomson Course Technology and Premier Press.

Jason Cootey, M.S., ABD
Project management and documentation management
Web Portfolio

The following are the five features:
Dynamism
“Genres are dynamic rhetorical forms that are developed from actors’ responses to recurrent situations and that serve to stabilize experience and give it coherence and meaning. Genres change over time in response to their users’ sociocognitive needs.” (pg. 4)
Situatedness
“Our knowledge of genres is derived from and embedded in our participation in the communicative activities of daily and professional life. As such, genre knowledge is a form of “situated cognition” that continues to develop as we participate in the activities of the ambient culture.” (pg.7)
Form and Content
“Genre knowledge embraces both form and content, including a sense of what content is appropriate to a particular purpose in a particular situation at a particular point in time.” (pg.13)
Duality of Structure
“As we draw on genre rules to engage in professional activities, we constitute social structures (in professional, institutional, and organizational contexts) and simultaneously reproduce these structures.” (pg.17)
Community Ownership
“Genre conventions signal a discourse community’s norms, epistemology, ideology, and social ontology.” (pg. 21)

The definition of dynamism has the biggest clues about the meaning of genre theory. At the same time, that is precisely where the meaning of genre unravels. A genre is a rhetorical form; however, the trick lies in the meaning of rhetorical form.

Is written communication a rhetorical form?
Is oral communication a rhetorical form?
Is software documentation a rhetorical form?
Is the high concept document a rhetorical form?

My point is if high concept documents are a genre and the general design document is a genre, then written communication is more of a classification then a genre. Does that mean that oral communication is a classification, rather than a genre?

I noticed this problem while writing my dissertation proposal. I need to lock down on my language so that I can keep things straight in my dissertation. But that isn’t the only problem. If the general design document is a genre and the document is formed by actors’ responses to situations then the fact that it is ignored in agile development is exactly what should happen according to genre rules. Community ownership is specifically about the ideals and norms of an Agile community that no longer needs to document everything. So there isn’t a problem with the increasing obsolescence of the general design document.

My next question shouldn’t be about a broken genre system but rather about the genre the discourse community uses in the place of the general design document. My dissertation is not about the general design document or about agile development. My dissertation is about the oral communication that developers use to replace much of their written communication genres. There is still a situatedness (they have knowledge situated in and sustained by the genre), even if I can’t account for it with genre theory. There is still a discourse community with norms and values, even if I don’t know the structure on which it is sustained and reproduced. There is another rhetorical form that has replaced the general design document. Yet I need to be careful when I say the replacement is oral communication because that is really the classification under which the actual replacement-genre actually resides.

Jason Cootey, M.S., ABD
Project management and documentation management
Web Portfolio

I made a Flash animation to track my race progress over the course.

Jason Cootey, M.S., ABD
Project management and documentation management
Web Portfolio