Write documentation from existing code

Case 1: ISO8583 documentation

The documentation for the existing code for processing financial transactions according to ISO8583 was written using the GitHub CopilotGitHub Copilot Chat feature in IntelliJ Idea.

Results are impressive. In 2 hours, Dmitry wrote 3 substantial documents describing the procedure in general, input data, and possible scenarios with output data. Dmitry estimated that he could barely write one single doc in 2h on his own, and the quality would be much worse. This work would be also assosiated with a lot of stress.

It was the first time Dmitry performed this use case, he spent the first hour figuring out Prompt engineering and experimenting, but later then things went much faster.

Lessons learned

Prompting is important

Provide as much context about the task as possible. Especially provide details about who will use the documentation, how, specifying criteria of success.

🔥 The "Avoid lengthy descriptions and marketing-style bullshit" line in the prompt helped a lot to avoid wordy results and hallucinations.

Repetition of some parts in the prompt seems also helpful.

Breaking down a large task into subtasks

According to How to use GitHub Copilot: Prompts, tips, and use cases , splitting tasks into smaller subtasks works really well. Subtasks should be well described in the context of the overall task.

Check the prompt below to see an example. First, the overall context is described in detail. At the end of the prompt, the model is asked to perform one particular step from the task.

Repeating requests

If you wrote a perfect prompt but it seems not to be working - just restart the request one more time. Sometimes it gives good results on the first run, sometimes on the 10th.

🔥 Extremely helpful!

Control your context

According to How GitHub Copilot is getting better at understanding your code GitHub CopilotGitHub Copilot analyzes open tabs for relevant parts of code. Keeping only 2-3 relevant tabs open seems to generate more relevant results.

Additionally, restarting the chat clears the contexts from previous results and removes irrelevant information.

Prompt

🔮
You're a professional tech writer and expert in programming and financial processes, in particular ISO-8583 expert.

Your task is to provide full and complete user-facing documentation of processing Shazam Financial Request message.

Resulting docs must be complete and full and well describe overall process.

You must focus on data and business logic and omit technical details like logging, error handling and meta objects.

All interfaces must be decribed fully.

This docs will be used by tech specialists and programmers to write test cases and implement other services working with our API so docs must be case-oriented and cover all cases and related changes in system behaviuor and output changes. Techincal specialists and programmers are familiar with financial systems and ISO-8583 so omit explaining the basics.

Docs must be structured in terms of scenarios. Each scenario must be described in way to reflect what's input data, how this scenarios is processed and what data exactly it returns.

Input and output data must be described fully and precisely.

You must provided detailed info about how this data changes and what it is. The resulting docs must contain these sections:

  1. Short overall description of the process in technical terms. Resulting description must be well-structured set of steps. Avoid lenghty descriptions and marketing-style bullshit.
  2. Detailed description of what data input we expect. All interfaces must be described fully and precisely as a code snippets.
  3. Structured set of scenarios i.e positive scenario, error scenario and others. Descriptions must be short and straight to the point. Avoid lenghty descriptions and marketing-style bullshit.
  4. Detailed descriptions of each the scenario. Each scenario must be described in terms of how this scenario is chosen, how it processes data, how it changes system state, what actions does it take and what exact data it returns.

Remind you that all non-important minor techincal detailes must be omited.

Provide response for section 4. You absolutely must avoid describing parts of previous sections.

Describing this section you MUST AVOID any descriptions from the previous sections you already provided earlier.