Using the prompting examples from this post in this prompt engineering series for reference, we’ll work through a mini technical writing project to learn how to create command-line interface (CLI) documentation. A CLI is a text-based method of interacting with a computer’s operating system.
Unlike other documentation, such as process or product documentation, CLI documentation is about adding documentation that’s accessed at the command line. Apps such as Terminal for Mac OS and Command Prompt for Windows allow advanced users to execute text-based commands and scripts.
For this post, chatbot research for this mini project will be demonstrated using Anthropic’s Claude AI.
Basic Guidelines
Before we start researching how to create CLI documentation, keep these guidelines in mind when conducting research with chatbots:
- Conduct basic web research if you’re unfamiliar with the topic before using a chatbot. This initial research will be needed to help you perform high-level validation to verify the information is accurate.
- Chatbots can and do hallucinate or fabricate factual information and present it like it’s a fact when it’s not. Initial research will give you baseline knowledge about the topic that you can use to evaluate their responses at a high level.
- As you get responses, perform high-level verification of each response to ensure the chatbot isn’t hallucinating. The goal isn’t to fact-check every sentence. You don’t want to have completed an extensive research-based conversation to learn that it contains factual inaccuracies and errors.
Brainstorming
Initial Google searches on this topic will reveal that there are multiple tools for creating CLI documentation. After completing initial research, a generic brainstorming prompt is a good starting point. The purpose of this type of prompt is to get a response containing multiple topic-related suggestions that should be useful for getting started.
The following prompt is broad and does not attempt to direct the type of results on CLI documentation that the chatbot will return in its response.
Brainstorming prompt:
How can I create command-line interface documentation?Brainstorming response (partial):
...
## Installation
`npm install your-cli-tool -g`
## Basic Usage
The basic syntax for using the CLI is:
`cli-tool <command> [options] <arguments>`
## Commands
### init
Initializes a new project in the current directory.
...
## Global Options
These options can be used with any command:
- `--help, -h` - Display help information
- `--version, -v` - Display version number
- `--verbose` - Enable verbose output
- `--config <path>` - Specify config file path
...The response shown here has been truncated, and the snippets above between ellipses (‘…’) are to illustrate the initial response to the brainstorming prompt. It mentions installing and using a cli tool but does not provide tool names. To see the full response from Claude click here.
This response isn’t useful because it doesn’t contain any guidance on how to create CLI documentation. It mentions bacis guidance for how to install and use a tool and basic syntax. It fails to mention a specific tool and is unhelpful for someone looking for a tool to help them create the documentation. It should have assumed that since the user’s question is vague, they would require information about specific tools. Since we’ve done basic research to understand what tools are avaible, the follow-up prompt can be tweaked to guide how the conversation with Claude will proceed.
Conduct Research
Remember, our goal is to learn how to create CLI documentation to be used at the command line. This has to include a tool name and syntax guidelines. It’s fair to say that the initial brainstorming prompt was unsuccessful because it did not include a tool name.
The following follow-up prompt and response snippets are examples of how to define the contours of Claude’s responses. Based on the first response, as shown above, or in full [here](ADD URL), Claude needs clarification on what we want.
Therefore, this follow-up prompt was created to redirect the conversation towards providing a list of tools. Once Claude provides a list of tools, the third prompt will request information about one of them. The goal is to focus the conversation to one documentation method.
Second prompt:
You didn't mention any specific tools I can use to create CLI documentation. Can you provide the names of tools or packages I can use to do this?Second response:
I'll share some popular documentation generation tools specifically designed for CLI documentation.
Here are some widely-used tools for generating CLI documentation:
1. **docopt** - Language-agnostic tool that generates command-line interfaces from documentation
"""Usage:
my_cli.py <file> [--count] [--verbose]
my_cli.py (-h | --help)
"""
from docopt import docopt
2. **Click** (Python) - Both a CLI framework and documentation generator
@click.command()
@click.option('--count', default=1, help='Number of greetings.')
def hello(count):
"""Simple program that greets NAME for a total of COUNT times."""
for x in range(count):
click.echo('Hello!')
3. **Commander.js** (Node.js) - Generates help documentation automatically
const program = require('commander');
program
.name('my-cli')
.description('CLI to do something')
.version('1.0.0');
...
Each tool has its strengths:
- **docopt**: Best for simple CLIs where you want to write docs first
- **Click/Commander.js/Cobra**: Ideal when building a CLI from scratch
- **MkDocs/Sphinx**: Better for comprehensive documentation websites
- **typedoc**: Great for TypeScript projects with API documentation needs
Would you like me to dive deeper into any of these tools or explain how to set up a specific one?The truncated response above shows that the follow-up prompt met its intended goal. The full response is here. It shows that there are indeed multiple CLI documentation tools available that we can explore.
Select A Tool
Since we don’t have specific programming language in mind, we will review the list of tools to find one that makes the most sense. In this case, it makes sense to explore the first suggestion docopt because it is language agnostic. The third prompt below asks for information about using docopt to create CLI documentation.
Third prompt:
OK, tell me more about how I can use docopt to create CLI documentation.Third response:
"""Naval Fate.
Usage:
naval_fate.py ship new <name>...
naval_fate.py ship <name> move <x> <y> [--speed=<kn>]
naval_fate.py ship shoot <x> <y>
naval_fate.py mine (set|remove) <x> <y> [--moored|--drifting]
naval_fate.py -h | --help
naval_fate.py --version
Options:
-h --help Show this screen.
--version Show version.
--speed=<kn> Speed in knots [default: 10].
--moored Moored (anchored) mine.
--drifting Drifting mine.
"""
from docopt import docopt
class Ship:
def __init__(self, name):
self.name = name
self.x = 0
self.y = 0
def move(self, x, y, speed):
self.x = x
self.y = y
print(f"Moving {self.name} to ({x}, {y}) at {speed} knots")
def shoot(self, x, y):
print(f"{self.name} shooting at ({x}, {y})")
class Mine:
@staticmethod
def set_mine(x, y, mine_type="moored"):
print(f"Setting {mine_type} mine at ({x}, {y})")
@staticmethod
def remove_mine(x, y):
print(f"Removing mine at ({x}, {y})")
def main():
arguments = docopt(__doc__, version='Naval Fate 2.0')
# Ship creation
if arguments['ship'] and arguments['new']:
for name in arguments['<name>']:
ship = Ship(name)
print(f"Created ship {name}")
# Ship movement
elif arguments['ship'] and arguments['move']:
ship = Ship(arguments['<name>'][0])
speed = arguments['--speed']
ship.move(arguments['<x>'], arguments['<y>'], speed)
# Ship shooting
elif arguments['ship'] and arguments['shoot']:
ship = Ship("CurrentShip")
ship.shoot(arguments['<x>'], arguments['<y>'])
# Mine operations
elif arguments['mine']:
if arguments['set']:
mine_type = 'moored' if arguments['--moored'] else 'drifting'
Mine.set_mine(arguments['<x>'], arguments['<y>'], mine_type)
elif arguments['remove']:
Mine.remove_mine(arguments['<x>'], arguments['<y>'])
if __name__ == '__main__':
main()This response from Claud about docopt is helpful because it provides information about the tool and gives an example of how to use it in Python. We can dig into the details of how docopt works, the languages it’s available in, and the syntax to use here. The entire response can be found here.
At this point, the conversation can continue to dive into how docopt works and best practices. For our purposes, it’s enough information to know that there is an answer to our question on how to create CLI documentation.
Summarize The Research
To wrap up the conversation, we’ll ask Claude to create a summary about what was discussed. A summary isn’t necessary but it’s helpful to have the chatbot present the conversation highlights.
Chatbots are good at summarizing information, and the end of a research-based conversation is a good time to request one. The key is to be clear about what it should summarize and how it should summarize it. We’ll keep the summary request prompt simple.
Summary prompt:
Summarize what we've discussed so far.Summary response:
Here's a summary of our discussion about creating CLI documentation:
First, we covered a general approach to structuring CLI documentation, including essential sections like installation, usage, commands, configuration, and troubleshooting.
Then, we discussed several popular tools for generating CLI documentation:
- docopt - Documentation-driven CLI builder
- Click (Python) and Commander.js (Node.js) - Framework with built-in docs
- Cobra (Go) - Generates docs and man pages
- clap (Rust) - Argument parser with doc generation
- MkDocs and Sphinx - Static site generators for documentation
- typedoc - TypeScript/JavaScript documentation generator
Finally, we did a deep dive into docopt, showing how it:
- Uses a documentation-first approach
- Requires a specific docstring format at the start of files
- Handles commands, arguments, and options through standardized syntax
- Automatically parses command-line arguments based on the documentation
- Makes it easy to maintain documentation since it's tied directly to the code
Would you like to explore any of these topics in more detail?This summary wasn’t requested in a specific format and the combination of paragraphs and lists is fine for our purposes. If you wanted a specific output format include those requirements in the prompt. For example, the prompt could have requested a narrative format, without lists or bullet points, and to be 100 words in length.
Conclusion
As a technical writer, there will be many projects where you aren’t familiar with the subject, documentation format, or both. In these cases, use a chatbot as you partner to get a headstart and throughout the project. They aren’t perfect by any means but they do add value to your work and can save you time and effort.
About the author
Renise is the owner and manager of Visually Written, a technical writing and communication company. She offers a range of technical writing services including API documentation and other technical documents.
