What are the best practices for documenting a control system program in a new language?

1 Know your audience

The first step to effective documentation is to know who will read and use your code. Is it your client, your colleague, your supervisor, or yourself? Depending on your audience, you may have to adjust the level of detail, the format, and the style of your documentation. For example, if you are writing for a client who is not familiar with the technical aspects of the control system, you may want to use more diagrams, screenshots, and plain language. On the other hand, if you are writing for a colleague who will work on the same project, you may want to use more comments, code snippets, and technical terms.

3 Use clear and concise language

The third step to effective documentation is to use clear and concise language that communicates your intent and logic. You should avoid using vague, ambiguous, or jargon-filled words that may confuse or mislead your readers. You should also avoid using unnecessary or redundant words that may clutter or obscure your message. For example, instead of writing "The function calculates the output value based on the input value and the parameters", you could write "The function outputs f(input, parameters)".

4 Explain the why and how

The fourth step to effective documentation is to explain the why and how of your code, not just the what. You should provide context and rationale for your design choices, assumptions, and limitations. You should also provide examples and scenarios that illustrate how your code works and what it does. For example, instead of writing "The loop iterates over the array and adds each element to the sum", you could write "The loop calculates the total power consumption of the devices in the array by adding their individual power ratings to the sum".

5 Update and maintain your documentation

The fifth step to effective documentation is to update and maintain your documentation as your code evolves. You should review and revise your documentation regularly to ensure that it reflects the current state and functionality of your code. You should also fix any errors, typos, or inconsistencies that you find in your documentation. You should also use version control and change logs to keep track of the changes and updates in your code and documentation.

6 Seek feedback and improve

The sixth and final step to effective documentation is to seek feedback and improve your documentation based on the input and suggestions of your readers. You should ask your audience to review and test your code and documentation and provide you with constructive criticism and recommendations. You should also learn from the examples and best practices of other control engineers who use the same or similar languages and frameworks. You should always strive to improve your documentation skills and make your code more understandable and useful.

7 Here’s what else to consider

This is a space to share examples, stories, or insights that don’t fit into any of the previous sections. What else would you like to add?