Bruce,

Strong words! Well, the figure callouts were probably written in 
first draft by whichever developer the writer is working with. And 
those callouts probably sound very odd indeed to anyone not 
accustomed to this writing environment. Like any technical or 
professional environment, it has its own language and some of that is 
very necessary and useful. The audience for this documentation is 
almost certainly other developers, and so the various abbreviated 
forms and what might otherwise sound odd (the particular thing a 
"role" is in this context, for example) will be familiar stuff.

If this were a book for end users, or if this were a textbook, the 
language would be very different. At the very least, the process 
analysis would be cleaned up to something like this --

      1. The system administrator creates the user role.
      2. The system administrator then sets role permissions.
      3. The developer sends a request to assume the role.
      4. [ProductX] returns the appropriate credentials for the role session.
      5. Using those permissions, the developer updates the /app folder.

Item 3 might even be instead "The developer calls the AssumeRole 
function," which is more precisely what is happening. But then the 
other items ought to be reworded accordingly, to reflect at a deeper 
level what each action entails.

A "callout" is a, well I suppose it's a publication term. It's a 
label used to identify parts of a figure, distinct from the caption 
(which titles the entire figure) or a legend (which adds additional 
information to the caption). A figure can be any sort of illustration 
or diagram or chart or whatever, though generally not tabular. 
Tabular info is numbered and titled in a distinct series, as tables.

You can find callouts discussed in any style guide that addresses the 
graphics of figures: Chicago, APA, AAA, and so on. They are not 
discussed in the MLA, not that I can find, at any rate, and I'm 
supposing that's because the MLA is used more for academic papers 
within the realm of the university, papers written in a word 
processing program where there is not the formatting capability for 
producing callouts, or indeed most types of figures. In a published 
book, however, they sometimes do come into play. And any figure 
complex enough to benefit from such can include callouts: the context 
need not have anything to do with computers.



Odile




At 6:35 AM -0700 9/14/12, Bruce Despain wrote:
>Odile,
>
>Please disregard this message, if I'm beating a dead horse.  It was 
>in disgust that I deleted your messages prematurely yesterday.  I 
>had not at first realized that your "callouts" were done by data 
>analysts, many of whom manifest a characteristic disregard for 
>natural language.  I think this feeling is reinforced 
>by philosophers who often express their consternation with the 
>weaknesses of human language.  (Mathematicians have largely 
>abandoned the use of natural language.)  I have worked with computer 
>programmers for years and should have known better.  In any case I 
>myself have long harbored a distain for the grammar of computerese 
>and the argot of texters, brought on by software developers often 
>with narrowly developed skills.  The latest (1999) dictionary in my 
>library does not even include this meaning of "callout."
>
>The process of assuming a role has probably been separated out and 
>was probably made part of the callout for clarity in what was more 
>accurately called out as a simple request for a role.  If other 
>requests were present along the same chain, it might make sense to 
>summarize the anticipated process of assuming the role requested. 
>The processes might suggest to the programmer that the developer 
>should confirm his request for a role before the role is assigned. 
>There is probably a "confirming" by the developer and then an 
>"assigning" by the software.  The result is that the "developer 
>assumes role requested."
>
>Bruce
>
>To join or leave this LISTSERV list, please visit the list's web 
>interface at: http://listserv.muohio.edu/archives/ateg.html and 
>select "Join or leave the list"
>
>Visit ATEG's web site at http://ateg.org/

To join or leave this LISTSERV list, please visit the list's web interface at:
     http://listserv.muohio.edu/archives/ateg.html
and select "Join or leave the list"

Visit ATEG's web site at http://ateg.org/