After completing our research on creating command-line interface (CLI) documentation and writing instructions for how to create this documentation, we can use a chatbot to assist with editing. We’ll use Microsoft’s Copilot to edit the instructions into a final version.
Chatbots are great tools for editing text snippets. They can provide constructive feedback depending on what improvements you need. Edits such as the language level – middle school, business professional, academic – can be made. You can change the text’s layout, structure, grammar, and punctuation, to name a few. The formatting options are limited to Markdown, a lightweight markup language.
You can request feedback for an entire document or snippets. Many chatbots have a character count limit. Copilot’s is 1,500 words. If the document is too long, break it into smaller chunks.
As always, because chatbots make mistakes and can hallucinate details, always review their work.
Edit The Instructions
Now that we understand how to create CLI documentation to describe command line commands or scripts the first step is to edit the information using the 7 Cs of technical writing and Grammarly (if you have it). If you don’t have Grammarly, using the chatbot without it is okay.
We’ll use the Docopt documentation created for a reverse string function as a result of our research. It’s already been through several rounds of offline editing. We will use Copilot to edit what we have to a final version. The first step is to ask Copilot to do a general analysis of the text without considering punctuation and grammar. If you subscribe to Grammarly, it’s worth editing it there before using a chatbot.
We’ve taken our research from the previous post and applied it to a simple Python function that reverses any text string. This function will demonstrate how to implement docopt in Python code. It can be found on Github.
General Prompt
The first step is to check the document as a whole to see what suggestions Copilot will offer. We want to see what changes the chatbot will make without specific user instructions. We’ll ask for general feedback and consider those changes before making a follow-up prompt.
General feedback prompt:
Analyze this text and tell me if it can be improved:
[[See this page for the full prompt and response](https://visuallywritten.com/microsoft-copilot-general-text-analysis/)]General feedback response snippet:
## Using Docopt to Create CLI Documentation
This post will demonstrate how to use docopt in Python code to create CLI documentation. Docopt is a tool for creating and presenting documentation for command-line functions and scripts. Finally, we will demonstrate what the help documentation looks like at the command line.
The example code we'll use is a reverse string function. The function itself is simple: It takes a string as input and returns it in reverse order. When invoked, the user is prompted to type a string, followed by the enter key. The reversed string will then be returned.
The implementation of docopt will be broken down into four steps:
1. Install docopt
2. Import docopt into Python
3. Add help documentation as a docstring
4. Implement docopt in the main function
At the end of this post, you'll see the completed implementation.
### Step One: Install docopt
To install docopt for Python at the command line, use the command below. We'll use [pip](https://pypi.org/project/pip/), Python's standard package manager.
pip install docopt
### Step Two: Import docopt
Open the `reverse_string_with_docopt.py` file and add an import statement above the function:
from docopt import docopt
### Step Three: Add Help Documentation
Add the following Python docstring to the beginning of the file, before the import statement. The docstring contains sections for usage and options. The usage section defines how to invoke the function with arguments and options, while the options section specifies the available long and short options.
"""
Reverse String
Reverses any input string.
Usage:
reverse_string.py [reverse]
reverse_string.py -h | --help
reverse_string.py -v | --verbose
Options:
-h --help Show this
-v --verbose Verbose mode
-q --quiet Quiet mode
"""
In the usage section, 'reverse' will invoke the function. The options '-h', '-v', and '-q' will return help information in various formats.
### Step Four: Implement docopt
Add a `main` function to specify how the function and help documentation will be invoked. The `arguments` variable will receive the arguments passed from the command prompt, and the if/else block will execute the code based on the argument provided.
if name == 'main':
arguments = docopt(doc)
if arguments['reverse']:
string_to_reverse = input('Enter the string to be reversed: ')
reverse(string_to_reverse)
else:
print(arguments)
The argument is provided at the command line immediately after the Python script's name. The `__doc__` parameter could be a docstring or another string that contains a help message to be parsed.The suggested changes are subtle but helpful. It suggests several heading modifications that help to clarify the purpose of each section. The third paragraph in the introduction was modified to be a list, which is a genuine improvement on the introduction’s readability. The full response is available here.
Targeted Prompt
Based on Copilot’s general feedback, we can request targeted improvements to sections of text. The demo usage section could be improved to add some more text. We won’t worry about grammar and punctuation at this point.
Targeted feedback prompt:
Could you add more text to this? It's too short and isn't descriptive enough.
## Demo Usage
To execute the code, navigate to the directory where the file is located or use the complete path to the file. The command below will invoke the function without displaying help documentation.
python reverse_string_with_docopt.py reverse
You will be prompted to enter the string to be reversed. The reversed string will be displayed after hitting enter.
docopt_reverse_string_function_result_screenshot.png
To view the reverse function's help documentation, use the options `-h` or `--help`.
python reverse_string_with_docopt.py -h
The result will display the help documentation added to the top of the file.
docopt_reverse_function_help_documentation.png
When `-q` is invoked, it shows which option was used.
docopt_reverse_function_quiet_option.pngTargeted feedback response:
Absolutely, let's make it more comprehensive.
## Demo Usage
To execute the code, navigate to the directory where the file is located or use the complete path to the file. The command below will invoke the function without displaying help documentation:
python reverse_string_with_docopt.py reverse
You will be prompted to enter the string to be reversed. After hitting enter, the function will display the reversed string.
For example, if you input the string Hello, World!, the output will be:
!dlroW ,olleH
Here's a screenshot showing the result after running the command and entering a string to be reversed:
### Viewing Help Documentation
To view the reverse function's help documentation, use the `-h` or `--help` options. These options provide users with guidance on how to use the script.
Run the following command to view the help documentation:
python reverse_string_with_docopt.py -h
The output will display the help documentation added to the top of the file. This includes details on the available commands and options.
Here's an example of the help documentation displayed in the command line:
### Using Quiet Mode
When the `-q` option is invoked, it will display the current status of all options. This can be useful for debugging or understanding which options are active.
Run the following command to see the options status:
python reverse_string_with_docopt.py -q
The output will look like this:
{'--help': False,
'--quiet': True,
'--verbose': False,
'reverse': False}
Here's a screenshot illustrating the output:
This example demonstrates how docopt simplifies the process of creating CLI documentation in Python, making your scripts more user-friendly and easier to understand. By following these steps, you can ensure your command-line tools are well-documented and intuitive for users.
If you have any more specific aspects you'd like to expand on or any other improvements in mind, let me know!The targeted suggestion and added text above are a practical addition to that section to define each part of the demo more clearly. It can be easily integrated into the post. The entire targeted response is here.
Final Edit: The Conclusion
Now that we’ve made some edits to the main parts of the post, we’ll next clean up the conclusion. We want the chatbot to take what we’ve already shared to create a new conclusion. Instruction will be provided to add some guidelines around what the conclusion should look like.
Conclusion section prompt:
Now write a conclusion using what we've already discussed. Use no more than five bullet points to make it. Each bullet point should be three sentences long.Conclusion section response:
Here's a concise conclusion in five bullet points:
- This example illustrates the installation and use of docopt with Python, streamlining the creation of command-line interface (CLI) documentation. By following simple steps, you can make your CLI tools more user-friendly. This greatly enhances the usability and accessibility of your scripts.
- Docopt supports various programming languages such as C++, Go, and Ruby, in addition to Python. This cross-language compatibility ensures that you can utilize docopt in different development environments. For more information, you can explore [GitHub](https://github.com/docopt).
- With docopt, your scripts can automatically generate help documentation from your docstrings. This assists users in understanding and using your scripts effectively. It also saves time by eliminating the need for writing separate help documentation.
- Although CLI documentation improves user interactions, it should complement rather than replace comprehensive documentation like webpages or PDFs. Detailed documentation provides in-depth explanations and examples. CLI documentation serves as a quick reference tool.
- Implementing docopt promotes maintainability and standardization in your code. It ensures that your command-line tools are well-documented. This leads to improved code quality and a better user experience.
Let me know if there's anything else you'd like to refine or expand on!The bullet points in this Copilot response will work with some minor modifications. They fit into the post’s existing organization and narrative.
Conclusion
This demonstrated how to use Microsoft Copilot, or any other chatbot, to speed up editing technical documents in general or for targeted sections. They allow us to speed up the editing process. They make it quick to create multiple edited versions for consideration. The post we used to make these edits can be seen here in it’s final version.
