Genre Analysis > Workflow Document

Step 1. Collect samples of the genre.

Determine where you need to look to find samples of the genre you plan to analyze. For example,
scholarly articles will be housed in library databases, whereas menus are found in restaurants and film
reviews are found online. You need to gather a number of samples to understand the range of diversity
that characterizes your genre. You cannot identify patterns, similarities, and deviations if you’re only
looking at one document. Aim to collect at least three examples of the type of writing (genre) you intend
to analyze. These texts will be your “data set.” They will provide you with evidence to build an argument
about how that specific type of writing “works”— how it makes meaning in the world.

Malvik, S. (2022). Mastering Azure API management: A practical approach to designing

and implementing an API-centric enterprise architecture. Apress.

S. M. Sohan, C. Anslow and F. Maurer, "SpyREST in Action: An Automated RESTful

API Documentation Tool," 2015 30th IEEE/ACM International Conference on

Automated Software Engineering (ASE), Lincoln, NE, USA, 2015, pp. 813-818, doi:

10.1109/ASE.2015.92.

Weaver, J. L., & Dea, C. P. (2012). Pro JavaFX 2: A definitive guide to rich clients with

Java Technology (p. 1). Apress.

Step 2. Describe the genre in as much detail as possible.

The genre that I will be working on is API documentation. API documentation refers to documents
which contain information about how to use a software API. For example, if a developer wants to
show on their website how long it would take to get to a certain restaurant, they would most likely
use Google Map’s direction system which would be able to do that. This would be considered using
an API. However, for the developer who are unable to do so since they do not know how Googles
API works, they would probably want to obtain API documentation which acts as a user manual
for it.

Setting: Where is this type of writing found? How / when is it used?

This type of writing is found in places where code is written which may include technological institutes or
some computer applications.

Content: What topics, issues, and debates are covered within this type of writing?

The issues covered by this genre include data extraction and readability. When it comes to readability,
this essay will focus on reviewing sample API documentations and observing whether or not they meet
developers' standards. As for data extraction, this essay will provide a basic explanation as to what it is

Partially adapted from Scenes of Writing: Strategies for Composing with Genres, Devitt, Reiff, and Bawarshi, 2018.
and analyze samples of API documentation describing methods of using data from servers for use in an
application.

Participants: Who uses this kind of writing? Who writes it? Why? Who reads it? Why? Who avoids it?
Why?
The people who would use this type of writing include any programmer who was involved in creating the
API in question or someone who has enough experience using it to do so. This is because you could only
use an API while programming, which people outside of computer science/engineering fields are not
proficient at. The ones who would read these documents may include programmers to learn about or test
them. The readers would most likely include those who are new to the workforce as senior-level
programmers may already be equipped of an understanding of how a particular API works. The ones who
would avoid the use of an API include consumers/users as they are the ones who are using the software
instead of making it.

Purposes: What purpose is this type of writing supposed to fulfill for readers and writers? Does it always
succeed? Can you identify contradictions? Changes over time? Do all participants agree on the purposes
and the impacts of the genre?
The purpose of an API documentation is to teach readers how to extract data or use a function from a web
server from a particular company so that they wouldn’t have to get into the hassle of making the functions
themselves such as updating the current weather or keep track of how many wins a certain basketball
team has. It usually always works, but some of the issues it may readers may face include lack of context
as the writers always assume that the readers would have the technical knowledge to apply an API. It may
contain outdated information as APIs can be updated iver time to improve efficiency. However, it has
drastically changed over time since the first API was created; during the early 2000s-2010s as API
documentation started to become more user centric as it became more accessible through the internet. All
of the programmers in the world can agree on the purposes of API doucmentations is to allow
programmers to learn how to integrate foreign software int o their code to make life easier for them.

Tip: If you are studying genre samples that are all housed within a single publication venue or produced
by a single organization, it may be helpful to see how the publication/organization characterizes its work
on its website.

Step 3. Identify the patterns of the genre.

The major question: What common features do your genre samples share? These common features will
be visible in rhetorical, linguistic, organizational, and content-based choices:

a. What rhetorical appeals do you identify in the genre samples?

I identify logos to be the primary rhetorical appeal of this genre as writers use a logical structure
to explain how to use an API step wise. Additionally, the information in it is revised to ensure
that no errors woul dbe made at all since doing so would cause a lot of confusion amongst its
readers.
b. What types of words and sentences appear in the genre samples?
There may also be comments which are sentences outlining what a particular branch of code is
supposed to do. It may also empoy the use of coding snippets, showing how users are supposed to
use the correct syntax in order to use an API, just as how we must use correct syntax in writing
essays.
c. How are the genre samples organized? What kind of format or layout is common?

The genre samples are organized in a way that would maximize readability for other
programmers. Images are provided to enhance the reader’s ability to understand the text in this
genre. It also includes captions under images that attribute them with a figure number

Partially adapted from Scenes of Writing: Strategies for Composing with Genres, Devitt, Reiff, and Bawarshi, 2018.
 followed by a picture description and procides captioning to explain what the image is
for.

d. What kind of content is presented in the genre samples? What kind of evidence seems to be
privileged?
The type of content present in a genre example includes explanatory text such as the text containing how
a genre sample is organized just as the above explanation, followed by structured data demonstrating the
API in use and an update log showing updates made to the functionality of it. The type of evidence which
seems to be privileged in this genre includes documents which provide detailed instructions as to what a
specific API does and an example of how it could be used.

Step 4. Analyze the meaning of the patterns.

The major questions: Which points are most significant or interesting when you examine your notes for
parts A above? Do you notice contradictions or connections that can help you make a claim? Remember:
You are making an argument about how a particular type of writing “works.” This means you’re showing
YOUR reader how you think they should interpret or understand the type of writing you’re analyzing.
What makes a “good” or appropriate or innovative or unsuccessful version of this genre?

The points which I found to be the most interesting involve how this genre uses logos since it is used
make life easier for programmers. Secondly, another significant point is that the functionality of it is
designed to complete tasks which may take hours of work in seconds. One connection that can help me
claim this involves how I used a weather API to update the weather forecast on a website, which prevents
me from constantly having to update it myself. In the end, it could be considered innovative since

To further help with this “analysis” piece, here are some questions to consider:
What do readers and writers have to know or believe if they want to make meaning out of this type of
writing? Do all readers have that knowledge or those beliefs? If not, how does that impact their
interaction with the genre?

To make meaning out of this writing, readers should have basic programming skills which include
knowledge of high-level languages such as Python. They should also be able to grasp the concept of what
HTTP is, and the concept behind how an API works. If they do not know about this, then it will have a
severe impact on their ability to understand this genre, as only programmers use this genre to their
advantage.

What attitudes or assumptions shape this type of writing? Does the writing illustrate a certain attitude
toward the readers or the content? To what effect?

Some of the assumptions that go behind shaping this type of writing include the assumption that the API
is not deprecated or considered obsolete. In that case, it would be useless to provide documentation for
the API that is not being used by anyone. Additionally, it also assumes that the API will be used for its
intended purpose, such as how a writer providing information about a stock market API keeping track of
updated data relating to stocks would expect it to be used for analytical purposes, instead of being used
for something irrelevant such as a texting app. The writing illustrates the attitude that the ones reading it
are already professionals who know how to use APIs, which is why it takes an accessible approach, where
it briefly mentions what each function does. It does so to the effect that readers would only use the
documentation when they only need to obtain a small piece of information it, in which case they will be
able to do so due to accessibility.

Who seems to be “invited” to engage with the genre? Who seems to be excluded? What are the
consequences of these divisions? For example, do linguistic choices (e.g. technical

Partially adapted from Scenes of Writing: Strategies for Composing with Genres, Devitt, Reiff, and Bawarshi, 2018.
language) or content-based choices (e.g. undefined terms or complex equations) make the genre hard for
some people to understand? Are those people in the intended audience?

The only readers who would be invited to engage with this genre include developers or programmers who
could benefit from it. Besides them, no one else without coding knowledge would be included as they
would typically not be able to use it for their needs. The consequence of this division is that it only
contains technical lexicon which only developers would understand. Furthermore, linguistic choices make
this genre harder to understand as it includes a lot of terms related to computer science since it involves
vocabulary related to coding syntax software development, and backend development. The ones included
are the intended audience as they would physically benefit from being able to use APIs which greatly
reduce their workload.

What kinds of social realities does this type of writing make possible? What kinds of social realities do
they block, deny, or ignore? For example, an old activist website called “All the Stops” shows us how the
“data visualization” genre can reveal the depth of social problems disproportionately impacting people of
colour in New York City.

The type of social reality that make this genre possible is that of the tech industry. It allows workers in the
tech industry to become more efficient as without it, every application that we know may need to go
through the process of manual data transfers, delaying our progress in technology. It tends to ignore the
reality of privacy, as it may rely on consumers’ private data to provide services to them, just as how
companies may track user activity to provide personalized ads.

Step 5. Begin structuring your argument.

I. Draft a paragraph introduction that defines key terms, offers a context, and states a specific
claim.

● You know a lot about genre theory. Draw on our class readings to write a short to medium-sized
paragraph that defines what a genre is and gives your reader a sense of why this information is useful
or consequential. It will be essential to cite sources here.

● Now, craft a second paragraph that extends your definition and discussion of consequence. Here, you
want to offer a context that primes the reader to understand the specific genre you’ll be analyzing.
This can be a good place to use some of your notes from Step 2 above.

● You should state your claim (thesis) at the end of this second paragraph.

● To develop the claim, return to the notes you made in Step 3, Part a-d. Ask yourself: What are the
most interesting observations I’ve made? Do I want to focus on the linguistic, rhetorical,
organizational, or content-based features of this type of writing? Select 1-2 of these categories (not
all!), then fill in specific details from your Step 3 notes to craft a claim.

● Here are some sample templates that may help with crafting a claim:

Partially adapted from Scenes of Writing: Strategies for Composing with Genres, Devitt, Reiff, and Bawarshi, 2018.
 ● There is a lot of variability in how _________ genre tends to be organized. Regardless, I am
suggesting that all effective versions of this genre share the following linguistic choices and
rhetorical elements: plain language and personal narratives that create relatability.

● Undergraduate students are not necessarily the intended audience for ________ genre, but they
are often assigned to read these texts. Because of this, student readers need to expect technical
language and dense content and adapt their reading strategies accordingly.

II. Develop paragraphs/sections that support the claim.

● You know a lot about genre theory. Now draw on other things you’ve read for class and encountered
via independent research to develop paragraphs that support your claim. Each paragraph should have
a central, guiding idea that is stated clearly at the outset.
● For example, look at this claim: “I argue that the high degree of uniformity can help readers
orient themselves, but the long length of the genre samples, combined with the continued
reliance on technical terminology, contributes to this genre being unapproachable for most non-
experts.”
● Based on this claim, the reader knows what to expect in the multi-paragraph sections that follow:

● An evidence-based discussion of organization (uniformity and length)

● An evidence-based discussion of language (technical terminology)

● Evidence is derived from my “data set” of three Annual Review articles.

● The application of this information is to make a point about how the writing is
unapproachable/exclusionary.

Here is my rough draft:

According to Wardle and Downs, a genre is a “recognizable form of writing that responds to repeating
situations.”(p. 34). Moreover, genres can be seen as a template for following a unique set of formatting,
conventions, and styles in certain social situations. By following these frameworks, writers can
effectively convey their message to their desired audience through methods familiar to those who read the
chosen genre. However, the context itself may vary between different forms of texts as it is only designed
to “determine appropriate responses to different situations” (Dirk, p. 259). For instance, an employer can
post a job listing online and receive multiple resumes, each containing different responses. Consequently,
while adhering to similar expectations, diverse contexts will always exist within a specific genre.
This essay will analyze the Application programming interface (API) Documentation genre, which
correlates to what programmers encounter daily. But what is an API? It is similar to a menu acquired
from a restaurant (remote web server). Using the menu, you can use functions to obtain data from the
restaurant, such as using a command to acquire information that includes the weather forecast for today.
This essay will examine three samples of API documentation and demonstrate how readers can use them
in a way that is understandable for readers.

Partially adapted from Scenes of Writing: Strategies for Composing with Genres, Devitt, Reiff, and Bawarshi, 2018.
When it comes to API documentation, there needs to be more clarity as to how the context of each source
of documentation will be provided as some authors like to take a user manual approach, while others may
employ an article or book style approach. However, it does not change the fact that in this genre, each
provided sample shares similar features such as the use of the introductory section, the use of coding
samples provided through images, and the captioning shown to clarify the aspects of the provided
pictures.
API documentation also features its distinct method of introducing developers to new APIs compared to
most genres. According to Jacobson Et. al, writers like to outline rhetorical moves to carry out specific
goals. The same is true for API documentation, however, it is done gradually as it begins with an
introductory section outlining a specific API and a brief history overview. This aims to give developers an
idea of what it could be used for. As such, we see this happen in the opening for the API documentation,
Pro JavaFX 2, the sample opens with, “At the annual JavaOne conference in May 2007, Sun
Microsystems announced… JavaFX. Its stated purpose includes enabling the development and
deployment of content-rich applications on consumer devices”(Weaver et al. p. 1). In this passage, the
authors attempted to describe the introduction to JavaFX in the tech industry briefly and stated how it can
be used for a multitude of consumer devices. Therefore, the introduction sets the stage for developers to
dive deep into gaining an understanding of how the API works.
Another crucial principle of this genre is that it is prevalent for authors to provide code samples to
demonstrate how an API works. The code is embedded into the article text because it would be displayed
as a picture, where the code itself would have line numbers and indented as the indentation affects the
code functionality. For instance, in Sohan et al.’s article, SpyREST in Action, we see that they have
included a code sample in the API documentation, which involves line numbers from 1-10 and indenting
from the third line onwards.

This shows that the authors recognize the universal importance of properly embedding code into API
documentation while demonstrating how to do so correctly. Doing it accurately allows programmers to
read the code easily and copy it as they would not run into any bugs in the program if it is done correctly.
When we observe articles, it is customary to find captions under images that attribute them with a
figure number followed by a picture description. Such is true for API documentation, as pictures can be
too complicated even for the most senior-level developers to understand without proper context. In Sven
Malvik’s Mastering Azure API Management, we see captions given for the image showing how the
Postman interface works for testing APIs to see if they work,
As shown, it is labelled “Figure #” to make it easier for readers to refer to the screenshot above. It also
becomes apparent that the authors attempted to include text boxes in the picture to show what each
different part of the display is used to offer. This labelling is used to aid readers who are not familiar with
using the Postman application. In essence, the captioning and labelling of images in API documentation is
a crucial process in the genre since it ensures that the reader can understand the various processes the
authors conduct to use APIs.

III. Conclude by showing readers why your ideas matter.

● How does an understanding of your specific genre contribute to your audience’s understanding of
reading and writing in general? Can your argument be applied as a guide for “how to understand
________ type of writing” or “techniques to use if you must produce ___________ type of writing”?
Connect the dots and show your audience why your ideas matter ☺
● Check out the conclusion of some genre analysis samples if you’d like a concrete example of how to
do this.

I also recommend reviewing the sample DCAs to consider how other writers have executed these tasks.

Partially adapted from Scenes of Writing: Strategies for Composing with Genres, Devitt, Reiff, and Bawarshi, 2018.
This analysis of API documentation genre samples shows that API documentation is presented in a
manner where clarity and detail are the top priorities. Furthermore, in the genre, the introductory section
gives us a brief explanation of the history of a certain API to prove that it could be useful in real-world
applications. Images are shown to effectively teach those who learn better than visuals compared to plain
text. With that, the precise captioning of each image allows new developers or users in an app to easily
learn how to navigate it to both test APIs and use them. In conclusion, the user-centric style of API
documentation allows readers to use it as a comprehensive guide and a user manual for short solutions.

Partially adapted from Scenes of Writing: Strategies for Composing with Genres, Devitt, Reiff, and Bawarshi, 2018.