How to Write a Detailed Tool Summary
This recipe is a guide to developing a detailed summary for text analysis or other research-oriented tools, based on primary and secondary sources. It is particularly useful for providing information on legacy tools that are no longer available, but is also extensible to modern tools.
- The tool you wish to describe
- Access to an institutional library collection and its associated journal database subscriptions
- Primary sources such as software manuals, product websites (if available), or publications from the creator(s) describing the tool’s development and applications
- Secondary sources such as software reviews, or articles and book chapters describing its use, describing research using that tool, describing the tool’s relationship to a similar tool, etc.
- A platform to host the summary, such as TAPoR 3.0.
- Locate reliable sources for your chosen tool via your institution’s library collection, academic journal databases, Google Scholar, Google Books, bibliographies, etc. If the tool is recent enough to have a web presence, include the tool’s website or that website’s Internet Archive Wayback Machine capture.
- Assess the sources you have located for reliability and distance from the tool. For example, is the article from the tool’s developer, or does it include just a brief mention based on another source? Did the author(s) use the tool themselves, or are they commenting from a step removed?
- Collect notes, quotes and citations from each source on the tool. These should include who the authors were, the development process, its functions, its distribution, whether it was influenced by other tools, how it was applied in practice and so on. See Discussion for more information on this step.
- From your notes, develop a summary with inline citations and cited quotes provided as appropriate. For legacy tools, the summary should be written in past tense unless the tool is still in active development, or development concluded less than five years ago.
- Construct a bibliography of sources. Include direct links to sources (journal DOIs, websites, digital editions, etc.) where possible.
A tool summary is, in essence, a short paper providing key details about a tool. It should include:
- The basic details of its development
- Who developed it
- What the tool is intended to accomplish
- When development began and, if applicable, concluded
- Where it was developed (institution, location, etc)
- How it was developed (ex: what programming language was used, what influenced its development, whether it was influenced by or expanded on the functionality of a prior tool)
- Why the tool was developed (ex: What need did it meet? / What were the developers responding to by developing it?)
- System requirements (software or hardware)
- Distribution (sold commercially, shareware, available by request from the developer’s home department, available for download, etc.)
- How the tool worked in practice / what tasks it could accomplish
- Its strengths and weaknesses
- How it was received by its target audience and other users
- How it can be situated in terms of related tools (ex: Does it amalgamate functions that otherwise required several other tools? Offer a function unique to its type? Is a notable refinement of its primary function? etc.)
- Whether this tool has been influential on later tools (if available)
The first paragraph is best confined to one or two sentences; this will assist readers in determining the basic details at a glance. It includes, at minimum, the name of the tool, and a brief summary of its function. It can also include when it was developed, who developed it, whether it is closely related to another tool, or other particularly important information.
The body paragraphs should include (as applicable):
- The tool's function
- The intended audience.
- A basic description of how it works (including relevant algorithms, theories or processes included in its design)
- What systems it runs on (ex: punched card computers, mainframe computers, microcomputers, particular operating systems, system requirements, etc.)
- Whether it is a stand-alone tool or part of a suite of closely related tools
- What kind of input it accepts
- Whether the input requires preparation before it can be run through the program (ex: markup, a particular file format, preprocessing through another program)
- What users can and cannot expect from output (ex: what format output is in, whether it can be exported for further processing, whether it's intended for printing and visual interpretation, whether it is widely useful or can only be read by the source program, etc.)
- Information about prior versions (if applicable), and key additions or changes.
The conclusion should include an assessment of the tool, either from a reviewer or a developer.
Once the polished summary is finalized, it’s ready for publication on a platform like TAPoR 3.0.
TAPoR has numerous summaries for entries in its historic tool collection. Its procedure (which provided the source for this recipe) is available via the project wiki.