Writing Documentation and Comments with AI
Use an assistant to draft READMEs, docstrings and guides that are accurate, useful and kept up to date
A taste of a lesson
The assistant wrote a README for my project and it looks great, but it mentions a plugin system. I don't have one. Why?
It filled the README with features that projects like yours often have. Models write what is typical unless they are anchored to facts. Give it your actual code structure, your real install and run commands and a short list of what the project does, and tell it to describe only those, marking anything uncertain. Then check every sentence against the code and run every command. Delete anything you cannot point to. Which three things does your project actually do that a new user needs to know first?
Written by the teacher as an example. In your lesson the tutor answers your own questions, and like any AI it can be wrong.
What you will be able to do
- Match each type of documentation to its reader and purpose
- Give the assistant real code, commands and audience before drafting
- Edit AI drafts for accuracy, specificity and the reasons behind decisions
- Keep docs current with same pull request updates and tested examples
Lesson plan
- 1 Docs for readers Choose the right kind of documentation for each audience. Start
- 2 Feeding the assistant Give the assistant real material so drafts are accurate. Start
- 3 Editing AI drafts Turn a generic draft into accurate, specific documentation. Start
- 4 Comments worth keeping Write comments that explain intent rather than restate code. Start
- 5 Keeping docs current Prevent documentation from drifting away from the code. Start
Try asking
About this tutor
For developers who know their documentation is thin and want help writing it without producing generic filler. Assistants can draft READMEs, docstrings, API references, onboarding guides and code comments quickly, but they also invent features, describe what code obviously does instead of why, and drift out of date. You will learn which kinds of documentation matter, how to give the assistant the right source material, how to edit drafts for accuracy and usefulness, and how to keep docs current with simple checks. Suitable for developers of any experience who want docs people actually read.
Reviews
4.5
2 ratingsSample
- Ingrid L.Sample
Learned to delete useless comments and write why comments instead. Short and practical.
- Kemal D.Sample
Our README finally has working commands. The 'run every command in the draft' rule found three wrong ones.
About the teacher
I teach how to review, test, refactor and secure code written with AI help
9 tutors 320 lessons taught Sample
I care about what happens after the code is generated. My background is in code review, testing and application security, and I teach developers to treat AI output as a draft from a fast, confident colleague who has never seen production. We practise reading diffs carefully, writing tests before asking for code, refactoring old systems in safe steps and spotting...
See Ilse's profile and tutorsMore like this
Other tutors on the same or nearby topics.