How can you document code for non-technical users?

1 Know your audience

Before you start writing your code documentation, you need to identify who your non-technical users are and what they need to know about your code. For example, do they need to understand the logic behind your model, the assumptions you made, the results you obtained, or the recommendations you derived? Do they have any background knowledge or familiarity with the problem domain, the data sources, or the terminology? Do they have any specific questions or concerns about your code? Knowing your audience will help you tailor your documentation to their needs and expectations.

2 Use plain language

One of the main challenges of documenting code for non-technical users is to avoid jargon, acronyms, and technical terms that they may not understand. Instead, you should use plain language that is simple, concise, and precise. You should also explain any concepts or terms that are essential for understanding your code, such as the objective function, the constraints, the variables, or the parameters. You can use analogies, examples, or diagrams to illustrate your points and make them more relatable. For example, instead of saying "we used a linear programming model to optimize the production schedule", you could say "we used a mathematical method to find the best way to allocate the available resources and meet the demand".

3 Provide context and purpose

Another challenge of documenting code for non-technical users is to provide enough context and purpose for your code without overwhelming them with details. You should explain why you wrote your code, what problem it solves, how it works, and what outcomes it produces. You should also highlight the main features, benefits, and limitations of your code, and how it relates to the overall project goals and objectives. You can use headings, subheadings, summaries, or introductions to organize your documentation and guide your users through your code. For example, you could start your documentation with a brief overview of the problem statement, the data sources, the model formulation, the solution method, and the results.

4 Use code comments wisely

Code comments are the text that you write within your code to explain what your code does, how it does it, and why it does it. They are usually preceded by a symbol, such as #, //, or /*, to indicate that they are not part of the executable code. Code comments are useful for documenting code for non-technical users, but you should use them wisely and sparingly. You should only comment on the parts of your code that are not self-explanatory, such as complex calculations, tricky logic, or important decisions. You should also avoid repeating what your code already says, such as variable names, function names, or parameter values. Instead, you should focus on the meaning, the reasoning, and the implications of your code. For example, instead of commenting #x is the number of units produced, you could comment #x represents the optimal production level that maximizes profit.

5 Use code examples and outputs

Code examples and outputs are the concrete demonstrations of your code in action. They are useful for documenting code for non-technical users, because they show how your code works, what it does, and what it produces. You should use code examples and outputs to illustrate your code functionality, to validate your code correctness, and to communicate your code results. You should also use appropriate formats, such as tables, charts, graphs, or dashboards, to display your code outputs in a clear and appealing way. You should also include captions, labels, legends, or annotations to explain your code outputs and highlight the key findings or insights. For example, you could use a code example to show how your code inputs the data, applies the model, and generates the solution, and then use a table to show the optimal production schedule and a chart to show the profit curve.

6 Get feedback and revise

The final tip for documenting code for non-technical users is to get feedback and revise your documentation. You should ask your non-technical users to review your documentation and give you their opinions, questions, or suggestions. You should also test your documentation by asking your non-technical users to follow your instructions, run your code, and interpret your outputs. You should then use their feedback and your own observations to improve your documentation and make it more user-friendly, accurate, and informative. You should also update your documentation regularly to reflect any changes in your code, data, or requirements. By getting feedback and revising your documentation, you can ensure that your code documentation meets the needs and expectations of your non-technical users.

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?