For several decades, scholars have explored how humans and computers might collaborate [1,2,3,4,5]. Early work largely focused on a zero-sum "trade-off" model in which a finite conceptual pool of "initiative" was to be split between human and computer. Typical approaches asked, in effect, "who goes first?" and many models went no further than a single cycle of human-initiates-and-AI-responds or AI-initiates-and-human-responds (e.g., [6]).
More recent work has deconstructed the older concept of unitary "initiative" into a flexible and collaborative framework in which increased initiative by one party (e.g. human) does not imply a decrease of initiative by the other (e.g. AI) [7]. In addition, the "mixed initiative creative interface" (MICI) framework analyzed by Deterding et al. [1] and Spoto and Oyelnik [5], further developed by Muller et at. [3], specifically details how human and AI partners interact in creative tasks as a series of back-and-forth exchanges.
In this paper, we examine how humans interact with a generative AI model in the context of writing data science documentation. We specifically aim to extend the human-initiates-and-AI-responds interaction pattern to include a step in which a human may make subsequent edits to the outputs of the model. Prior work by our team has explored how data scientists use various kinds of models -including a GNN-based generative model -to aid the task of adding documentation to data science code in Jupyter notebooks [8]. In this paper, we conduct a deeper analysis on the edits made by participants in that study, to understand the nature of their edit-patterns and how they "compensate" or "augment" the output of the generative models. Through a thematic analysis, we developed a classification of participants' edit-patterns.
We found that 85% of participants' edit-patterns fully accepted the algorithmically-generated text, or built upon the generated text; and only 15% of the instances involved a complete rewrite. At first glance, these results suggest that the generated text was well-accepted. However, participants modified the generated text in 41% of the cases. Thus, (1) a human requests the generation of text; (2) the AI provides that text; and then (3) the human makes a decision to use -or not to use -that text, and (4) may go on to edit the generated text. In the future, these threeto-four dialogic "moves" could become the basis for an extended conversation between human AI.
In this paper, we develop a taxonomy of edit-patterns, discovering that some edits added missing details while other edits explained the function of the code. A third category of edits was primarly concerned with modifying the formatting or style of the documentation.
We discuss recent work in the area of AI and machine learning applied to data science and software engineering, as well as the application of generative models to this domain. We also discuss recent studies on human interactions with generative models in software engineering.
In recent years, techniques from AI and machine learning have been applied to various tasks in software engineering, including code completion [9,10,11,12], code translation [13], code classification [14,15], API recommendation [16,17], variable and method naming [18,19], type inference [20,21], bug detection and repair [22,23,24,25,26,27], comment description and generation [28,29,30,31,32,33], code change summarization [34], and code clone detection [35]. Allamanis et al. [36] provides a comprehensive review of the use of AI and machine learning within data science and software engineering. The emergence of generative AI techniques for natural language, such as GPT-2 [37] and GPT-3 [38], have also been reflected in code-centric use cases: Brockschmidt et al. [39] proposed the use of generative models for source code, and Tufano et al. [40] used generative models to fix bugs. In this paper, we conduct a deeper analysis of participant interactions with Wang et al. [8]'s Themisto documentation-generation system, which incorporates a GNN-based generative model for generating comments from code.
In a recent study, Weisz et al. [41] examined the use of an unsupervised neural machine translation (NMT) model in addressing a task in application modernization, specifically regarding translating code from a legacy language to a modern one. They found that software engineers would be tolerant of errors or mistakes in the output of an NMT model, as the code produced by that model would be subject to the same review and testing procedures as code produced by everyone else on their team. In addition, a code highlighting feature that indicated where in the code human attention might be needed, based on an aggregation of the model's token-level confidences, was very desirable. Although a subsequent analysis by Agarwal et al. [42] demonstrated how current metrics of model confidence may not necessarily correlate with external truth of code quality (approximated by lint errors), the ability for a generative model to be able to "ask for help" via code highlights was nonetheless highly valued by software engineers. In this work, we push even further by seeking to understand whether a generative model can also specify what kind of it help it needs from its human user.
In order to understand the co-creation process of data science documentation, we examined Themisto [8] a prototype code documentation generation system that supports data scientists in writing documentation for computational notebooks. 1 Wang et al. [8] conducted an evaluation of Themisto with 24 data science professionals. In this section, we briefly discuss how Themisto generates documentation from code, as well as the user study setup and data collection methodology.
We implemented the automatic documentation generation system as an extension to JupyterLab (Figure 1). The extension generates three types of documentation for a given code snippet. The first type of documentation is generated using a Graph Neural Network based approach [45] which is commonly used in code summarization tasks. The second type of documentation is generated by retrieving relevant external API documentation for a code function (e.g., functions defined in Pandas2 , Numpy3 , and Scikit-learn 4 ). Lastly, the extension also provides a prompt-based approach where users are given a short prompt to manually create the documentation. For example, if a code cell contains a graphic output, the extension would generate the prompt to ask users to interpret the output.
We are interested in how users make revisions on the suggested explanations. Thus, we recruited 26 data scientists to add documentation to a given draft notebook using the prototype. We prepared two draft notebooks with the same length (9 code cells) and similar levels of difficulty, but for two different problems. Each partici-pant was randomly given one of the two notebooks and asked to document the notebook within 12 minutes; two participants failed to complete the task within that timeperiod, and were excluded from further analysis. Before the study, we provided a quick demo on the functionality of the extension.
We collected the completed final notebooks (N=24) after participants finished the task. All study sessions were conducted remotely using a teleconferencing tool and we recorded participants' screens with their permissions.
After the session, we conducted a retrospective interview to ask about their experience and feedback. We wanted to understand how participants used the algorithmically-generated documentation. For orientation, we review that 13 participants made documentation choices and optional modifications in each of nine markdown cells in each of two notebooks ("Covid" and "house") -i.e., 13 participants for each notebook. In the data from each notebook, we discovered two participants (per notebook) who did not complete the task, or who created extra cells. We could not be certain how to "map" these extra cells to the structure that was common across the other 11 participants. Because we wanted to compare participants' responses in a disciplined way, we treated each of these people (who created extra cells) as outliers, and excluded them from analysis. This exclusion left us with 11 participants per notebook who had worked with P07-house+6 using the specified method the algorithmically-generated documentation.
To prepare the documentation for analysis, we grouped all of the texts for each cell together (separately for each notebook). We then used a bag-of-words method to identify words (tokens) that were not included in the algorithmically-generated documentation. In the quotations in this paper, the participant-introduced words appear in bracketed [blue-ink]. 5 Table 1 provides an illustrative example. This was a slightly conservative method for identifying new text, because we might fail to detect that a participant had typed "data" (for example) in their own usage, rather than including the word "data" from the algorithmically-generated text. However, we used this method only to orient ourselves to the texts.
We next read each text by each participant. After readings all of the texts, two researchers agreed upon a codebook of edit-patterns. One researcher than applied that codebook rigorously to all of the texts.
We identify each text in terms of the participant number (1-26, with two non-completers and two outliers excluded), the notebook ("covid" or "house"), and the cell in the notebook (1-9). For example, "p21-house+4" refers to participant 21, in the "house" notebook, in the 4th markdown cell.
this workshop paper, we present new analyses to examine the edit-patterns in the 41% of the cells with participantedited documentation. There were few statistically significant differences between participant data from the two notebooks. We briefly report those analyses here, before the qualitative analyses that are the core of this paper. Because we did not find differences between the two notebooks, we will then perform content analyses of participants' text on the combined data from the two notebooks in Sections 5 and 6.
We provided three different Sources of documentation: AI, Query, and Prompt. A chi-square analysis found no significant differences in the proportions of Sources chosen by participants in each notebook. We also looked at combinations of Sources -i.e., no discernable source vs. a single source vs. multiple sources. Again, a chi-square analysis showed no significant differences between the notebooks.
We describe distinct Edit-Patterns below in Sections 5 and 6. Here, we briefly state that we used chi-square tests to examine whether participants used different editpatterns between the two notebooks. Only one of editpatterns showed a significant difference, and that pattern was concerned with the format (not the content) of the documentation (i.e., levels of headers in the markdown cell).
Similarly to the "combinations" analysis of Section 4.1, we found no significant differences across notebooks for cells with zero edit-patterns, a single edit-pattern, or multiple edit-patterns.
The preceding quantitative analyses showed only a single, stylistic difference in participants' work with the two notebooks. We therefore combine our qualitative analyses of edit-patterns across the two notebooks.
We manually coded the edit-patterns in each participant's text in each markdown cell, according to our codebook (Section 3.3.1). For the 22 participants in nine markdown cells, we thus coded 99 texts in each notebook, for a total of 198 coded markdown cells. We applied an informal version of thematic analysis [46], noting Braun's and Clarke's advice that there are multiple ways of conducting a thematic analysis [47]. Previous grounded theory and thematic analysis studies have involved from 6 to 74 participants [48,49], and so our sample of 22 participants is within that conventional range. Within this sample, we used the saturation practices of Guest et al. [50] (recommended by Ando et al. [46]) and Majid et al. [51], defining saturation by a code that appeared from at least two participants. We made no restrictions on the number of codes that we identified in a single text. Thus a text might have zero codes if the participant simply accepted the algorithmically-generated documentation, or it might have as many as three or four different codes in complex cases.
Participants expanded on the generated documentation by adding details. There were three subcategories of details: Contextual information, information about Thisstep (the current step), and information about Subsequent steps.
Contextual details could take several forms. P03-house clarified how the prior steps had produced materials that were used in the current step: In some cases, participants added specific algorithmic details that none of the generated texts had included. A repeated example was to mention (and sometimes discuss) root mean square error and its importance:
• ### evaluate a score by cross-validation [uses rmse as an evaluation metric] with [5-fold] cross-validation (p03-house+9)
• ### evaluate a score by [5-fold] cross-validation [using rmse] (p15-house+9)
We found a third edit-pattern that anticipated the next step (i.e., a subsequent cell) in the notebook. P08-covid briefly stated the use that the inputted data would be put to:
• ### read [and sanity check] the data (p04-covid+2)
However, in other cases, the participant provided a much richer description of the next steps, as in this recitation by P05-covid:
• ### Model A random forest is a meta estimator that fits a number of decision tree classifiers on various subsamples of the dataset and uses averaging to improve the predictive accuracy and control over-fitting the [first line below initiates] a model [instance] and the [second line] fits the model on the [training data] (p05-covid+8)
We have shown three edit-patterns in which participants have provided more detail than was available in the generated texts. These patterns might be considered as spanning an imagined audience's reading experience. In some cases, participants wrote Contextual information into the generated texts. This contextual information was generally retrospective -i.e., what should the reader have known in order to understand the code? In contrasting cases, participants focused less on context, and more on content within the current cell (This-step). Finally, in a few cases, participants wrote to anticipate the next cell or cells. In the Discussion, we will think further about this kind of participants' mental model of their audience's experiences.
We also wish to acknowledge that some of our category boundaries are fuzzy. The next category of edit-patterns poses the question -what is the difference between a Details edit-pattern and an Explanation edit-pattern? With further research, we may need to redraw this boundary.
Sometimes participants went beyond simple details, writing a more extended Explanation. P02-house and P15house provided brief examples, in which they added operational explanations of how to perform the activity in the cell:
• ### return the first 5 rows [(defvalue=5)] (p02-house+3) The Explanation edit-pattern brings in different types of information, including operational aspects and extended explanatory material about data files and programmatic resources. As we noted above, with more data, we may discover that Explanations may need to be combined with Details. Another possibility is that Explanations may turn out to be a subset of Tutorial edit-patterns, which we describe in the next subsection.
In a more complex pattern, participants appeared to be teaching the reader how to do the analysis. For example, P05-covid provide detailed explanations about how to carry-out a series of operations in python: Finally, we note that P24-covid took a somewhat different tutorial strategy. They left the original generated text intact as provided by the algorithm, and then added a link to more information about the python code-structures that were used in the cell that the algorithm had described:
• p24-covid/expt ### replace a specified phrase with another specified phrase [[for more information about lambda](https://realpythoncom/python-lambda/)] (p24-covid+4)
Tutorial edit-patterns went much further than Explanation edit-patterns (which themselves had gone further than Details edit-patterns). Tutorial edit-patterns provide not only how-to information, but also interpretations of the meaning or purpose of actions, and in one case a link to further information.
In the preceding subsection, we began to describe a dimension of increasing complexity in the information that participants provided, and also (we infer) increasing effort on the part of the informants to think "beyond" what was given in the generated text. The last edit-pattern in this series involves even more "beyond" work: beyond previous transformations of the generated text, and probably beyond previous levels of effort. We call this editpattern "Rewriting, " because it involves nearly complete replacement of the generated text.
It may be that the generated text in certain cells led to more instances of Rewriting. For example, three different participants rewrote the generated text of cell 4 of the House notebook:
• ### [join features from train and test into one df] (p15-house+4)
• ### [transform and clean] the [data] (p22-house+4)
• ### [concat train and test col salecondition] (p02-house+4)
Similarly, two people rewrote the contents of cell 9 of the Covid notebook:
• ### [make predictions] (p17-covid+9)
While it initially appears that Rewritten cells were relatively brief, we found that two other participants Rewrote the same cell (cell 9 of the Covid notebook) at much greater length: In some cases, partipants Rewrote the generated text at a higher level of sophsitication:
And in one case, the participant Rewrote in a very summary fashion, only listing a series of steps:
• [modeling process -subsetting data -cleaning datagetting rid of nulls -model training] (p14-house+4)
In the Rewriting edit-pattern, we see diverse strategies, ranging from brief summaries to extensive new text, as well as high-level abstractions. Significantly, in multiple cases, participants made distinctly different Rewritings of the same generated text (i.e., in the same cell of the notebook). Thus, while the category of the edit-pattern is the same, the individual strategies can be quite different. We recall that we saw analogous patterns in the This-step Details edit-patterns of subsesction 5.1.2. While there may be agreement among participants that the generated text in certain cells requires a certain type of change, participants clearly adopt different strategies about how to make those changes.
In this part of Results, we have examined how participants changed the contents of the generated texts. Figure 2 summarizes a dimension that runs from simple Details, to more complex Explanations, to instructive Tutorials, and finally to complete Rewritings of the generated text. Collectively, participants have an extensive repertoire of edit-patterns that they apply to particular problems in particular documentation cells. We next examine more stylistic changes that participants applied to generated text.
Sometimes in combination with other edit-patterns, participants modified the markdown formatting from the generated texts. Initially, all markdown texts were provided at the same hierarchical level (###). In multiple cases, participants modified those levels, placing texts in super-order / sub-order relation to one another:
ues [which are replaced with] the [mean value] for [that feature] this is [also known as column-wise meanimputation] (p11-house+6) P17-covid modified the header markdown specification when combining the contents of two different forms of generated text:
Further research will be needed to understand if these stylistic/formatting edits are related to changes to the words in the documentation.
Some of the changes to content appeared to clarify what was being done in the code. The primary subcategory of these changes was to add a verb to a noun-phrase:
Some participants added the verb in a different position in the sentence. In these two examples, we see P21-covid and P24-covid modifying the same generated text, but with different versbs:
However, participants also engaged in more complex ways of completing a sentence. For example, P01-covid both added a verb and changed the object of that verb:7
• [generate] the [predictions] (p01-covid+9)
While editing the same cell, P02-house, P07-house, and P15-house added the same verb, but then made different modifications to the object of that verb:
• ### [fit] a lasso linear model [to the training data] (p07-house+8)
There were also even more complex cases, in which it is not clear if the participant's purpose was to complete a sentence Here, we repeat one example of P17-covid from the previous subsection, which illustrates our point about the ambiguity of complex cases:
random forest is a meta estimator that fits a number of decision tree classifiers on various sub-samples of the dataset and uses averaging to improve the predictive accuracy and control [over-fitting)] (p13-covid+8)
We observed a further stylistic modification which appeared to make the generated text more conversational.
To avoid asserting our own judgments of what "conversational" might mean, we show only examples in which the participant added a personal pronoun -typically "we" or "you". For ease in reading, we have bolded those pronouns in the following examples:
• importing libraries:
We acknowledge that the distinction between content and style is far from clear (e.g., [53]). Therefore, we consider that our current categorization of Content-Related edit-patterns and Stylistic edit-patterns may require revision. With larger datasets, we may for example conclude that Conversational Tone is more related to Tutorial changes, and less related to "style. " The same may occur with Completing a Sentence. We will also need to understand better the relationship of header-styles to content in brief documentation text snippets.
We computed the percentage of the Content-edited cells in which each of the above Content edit-pattern appeared. Details edit-patterns were the most frequent. This may be unsurprising, because these kinds of edit-patterns took relatively little effort (Figure 2). In general, edit-patterns that were most costly of effort (Tutorial, Rewritten) had lower frequencies of occurrence, with Rewritten editpatterns occurring in fewer than 15% of the edited cells.
These results have implications for the design of algorithmic documentation systems. Taken together with our prior work on TransCoder, we can also see emergent ideas about how people can understand and make use of AI outcomes, even in the absence of formal explanatory systems (e.g., Explainable AI, or XAI). Finally, these two projects point us toward important questions in the design of future human-AI collaborative systems.
The results we reported on participants' editing patterns lead us to think about a few implications to further improve the automatic documentation approach. First, the Details edit-patterns, Explanation edit-patterns, and Tutorial edit-patterns are relevant to the purpose of the notebook and the target audience. We believe that a future version of the generative approach should tailor the automatic documentation based on the usage scenario. Data scientists can benefit from more candidate documentation where the level of details varied. With a larger dataset, we could associate these editpatterns to particular patterns in the algorithmicallygenerated texts. Based on those associations, we could modify the algorithms to anticipate the kinds of edits that humans have previously made (e.g., [54]). For example, if we can remove the need for Details-related and Conversational-Tone edits, then humans can focus on higher-value editing, such as Tutorials. We may then see emergent categories of even more task-specific and/or domain-oriented edit-patterns, when humans no longer need to put work into less significant edits.
One way to do this, is to include a reinforcement learning component into the algorithm that could learn from users' modifications to the proposed texts. Our current GNN model relies on the size of the training dataset to ensure the quality of the results. However, data science code snippets are patternless and are of limited use for generating explanations. In the future, we can combine deep reinforcement learning with our current GNN model [55] to improve the performance and generalizability of the results. This can help provide consistent stylistic documentation in terms of the writing style, sentence structure, and level of details.
In our earlier generative documentation paper [8], we learned that people accepted algorithmically-produced documentation in 45% of the cells. In this workshop paper's analysis of the 41% of edited cells, participants retained at least part of the generated text in over 85% of the cells (Details, Explanations, Tutorials). The fact that they chose to do the extra work to Rewrite in only 15% of the cells, is evidence that they mostly chose to work with imperfect text rather than to replace it. This outcome is consistent with our previous study of code translation, in which engineers reported that they preferred an imperfect translation to no translation at all. While we hope to improve our generative algorithms in both research programs, we also envision future studies in which we will calibrate the quality of the outcomes, to determine the threshold of "poor quality" below which an algorithm should not be deployed. We could then perhaps provide a more "skeletal" outcome, such as an outline of documentation rather than full-text. We could also treat "poor-quality" instances as higher-priority opportunities for algorithmic improvement.
We now consider each of our research programs (translation and documentation) in terms of published patterns of human-AI collaboration [6,1,2,4,7,5]. In both of our studies, the human provides some initial information (source code in both cases), and the generative algorithm responds with a proposed outcome text (target code or documentation, respectively). After that, with minimalist support, the human has to make their own way -e.g., by choosing among alternative translations for sections of the target code, or by manually editing the documentation.
These patterns remain consistent with simple initiative models (e.g., [2,4]), and fall short of the richer on-going interactions of some of the experimental MICI applications [1,5], with their potential of AI-augmentation in support of skilled human work. We anticipate that future versions of both projects could move toward longer and richer exchanges between human and AI (e.g., [6]).
If the human edits the target code in the TransCoder project, then a secondary AI (e.g., [12]) might assist by generating completion of the human's new code or suggesting additional modifications to the target to remain consistent with the changes. This secondary AI would be "aware" of the original code, and could provide additional type-ahead support, advice, or consultation as needed. Similarly, if the human edits the generated text in the Documentation project, then a secondary AI (e.g., [56]) could provide assistance with Details types of edits, but could also provide language-quality (Stylistic) support for more complex Tutorial accounts, or even narratives (e.g., [57]).
Ask for Help?
Our work highlights an opportunity for enriching human interactions with generative models. At a base level, a generative model takes input (e.g. code) and produces output (e.g. documentation for that code). Agarwal et al. [42] demonstrate how a generative model can produce confidence scores alongside its output, and Weisz et al. [41] show the utility such scores can have in steering human attention toward reviewing portions of the output in which the model has low confidence. In this work, we demonstrate how having an understanding of the nature of human edit-patterns to a generative model's output can enable a generative model to not only identify where human attention is needed, but also how human effort can be used to improve the quality of its output. One of the interesting questions will be exactly how to choose among those alternatives -i.e., when is typeahead useful, and how should a watchful but respectful AI intervene with advice, and what dialogic or other communication structures should be involved in an on-going AI-human consultation [58,59,60])? Our experiences with the NMT algorithm in the TransCoder experiment showed that, with a sufficiently broad beam-search [61], we could generate a manageable set of alternative translations, which could be compared using an algorithm like [62] to determine regions of agreement between the translations as well as regions of uncertainty along with the alternatives considered for the uncertain regions. These alternatives could then serve as informal explanations -e.g., "Q: Why is the output marked as uncertain in this region? A: Because the algorithm considered multiple possible translations at this point, and this is what they were. "
The GNN in the Documentation project might also be modified to produce multiple possible texts, with similar explanatory power ("Q: Why is this documentation marked as uncertain... ").
If there are multiple, alternative outcomes with no emergent "most-probable" alternative, then this could become an initiation point at which the algorithm de-tects the need for human assistance. One way to implement this request-for-help is as a "human-in-the-loop" paradigm, in which the human responds to the needs of the algorithm. We also envision situations in which the human may be in the midst of editing code or text, and may ask the algorithm to serve as a text-assistant for the human's on-going editing work. This could become an example of the "AI in the loop" paradigm that we discussed at last year's workshop. In these ways, we could move from the relatively single-process "initiative" models of [2,4,7], and toward a more collaborative and on-going series of interactions as in [1,5].
In order to conduct a controlled study, we sacrificed ecological validity. We asked participants to document someone else's notebook. By contrast, the canonical case in Jupyter notebooks is to document one's own code. A future goal should be a more naturalistic practice of documenting my notebook.
Paradoxically, for precision of evaluation, we may also need to perform an even more controlled study, in which each person receives only one algorithm's text at a time. This approach could help us to assess each algorithmic approach more independently than in the preliminary experiment in this workshop paper.
We also note that our analytic method could be strengthened in future research. Our bag-of-words approach was insensitive to word-order, and we looked only at patterns of added words. Future work should also examine patterns of deleted words.
Finally, we note the obvious sampling weaknesses. We conducted a relatively small study in a single institution. We hope to examine similar practices in other settings, and with more participants.
In this workshop paper, we have addressed topics in human-AI collaboration in data science and software engineering. We reported text analytic results from a study of generative documentation, showing that participants accepted generated text with or without modification in the majority of instances. These results are consistent with our earlier work, in which engineers were enthusiastic about using imperfect NMT-generated translations of software code. Similarly, participants in this study were also quite ready to accept or to work with imperfect GNN-generated texts. We also analyzed the edit-patterns in the generated text, developing categories that suggest future work directions. Finally, going beyond early unidirectional models of "initiative, " we sketched promising directions for longer-term, on-going human-AI collaborations.