Learning outcomes
- Explain why documentation is important for both individual and team work in technical environments
- Create a well-organized README file that follows documentation best practices
- Evaluate documentation for clarity, accessibility, and completeness and identify specific areas for improvement
- Describe strategies for keeping documentation up to date and the consequences of letting it become outdated
Key Takeaways
- Write documentation for your future self and for teammates who weren't there; assume they know nothing about your decisions
- A README explaining what a project does, how to set it up, and how to use it is the minimum expectation in professional work
- Comments should explain why, not what; the code shows what it does, the comment explains the reasoning behind it
- Outdated documentation is often worse than no documentation; it sends someone the wrong direction with confidence
- Technical documentation is professional writing and will be read as a reflection of your work quality
Would you like to download my PowerPoint to follow along?
- Why documentation is important
- Making sure that you have a record for later reference, don't assume you'll remember details
- Sharing information with others on your team or at your company
- Having a reference for things that need to happen repeatedly, infrequently, or be done by lots of people etc
- Having a historical record so that you can see why something is the way it is without having to track down the original creator
- Having a place for information that doesn't require time from others to explain things to you
- Keeping a record so there aren't conflicting points of view, such as issues that get escalated to HR
- Why documentation is important, caution: by a company who's product helps with documentation
- Writing documentation for others
- Writing for others means you need to think about how your document is organized
- Make sure that you have clarity in your words so that someone else can follow your train of thought
- Things like code comments can be used to make sure the next person using the code understands your thought process
- Examples and demonstrations are helpful so that someone else can understand how everything works
- Even if you think you will remember something, you won't, write the documentation for others so that you don't have to rely on your memory
- Assume your documentation can and will be shared widely, don't be inappropriate (examples include code comment hell)
- Multiple formats are helpful because you don't know who's going to read your document
- How to write software documentation
- Writing Better Documentation
- Writing documentation for yourself
- Keeping records for yourself is useful in school and at a company to make sure that you remember everything you've done, and have the receipts
- Documentation can look like anything including calendars, to-do lists, notes, meeting transcripts or even short thoughts, it's just important to have records that you can organize and find
- Example: Personal Accomplishments, keeping track of these can help when you need to argue for promotions or raises, or even if you are put on a PIP so that you can have a record in writing
- Example: Personal notes, keeping track of your thoughts and day to day work can help keep you organized, but also give you a written record, nothing is firm unless it's written down
- Example: Links to documentation that you use frequently or infrequently
- The Smart Way to Document Everything at Work
- Get Organized: Document Your Workflow
- Documentation Organization
- Documentation is only useful if people read it and can find what they need
- Different people will have different theories on documentation, but the commonality is that it needs to be clear and concise without being useless or obvious
- Such as I++ //This increments i by one!
- There isn't a one size fits all organizational principal, it's by what is needed
- Organization can change as your documentation evolves, as you keep it up to date you may find other organization options are required
- Keeping Documentation up to date
- One of the biggest failings with documentation is that it gets out of date and no one fixes it
- Fixing documentation should also include a schedule of checking to make sure it's up to date, this can include things like a list of what documents to change in specific scenarios
- Make a script to check your code examples to ensure validity
- Keep up a changelog or use version control so there is a dated record of the changes
- Fix anything you notice as an issue right away, don't assume you'll remember or have time to do it later
- Pragmatic ways of keeping documentation up to date
- Technical documentation
- An important piece of technical documentation is an overview or a roadmap of how something is put together
- This documentation can be written and used for anything such as setting up servers, running scripts, or even working with services that aren't used often such as renewing domains or tax reports
- The documentation is important to make sure you are following all the known steps, this can sometimes include a checklist to ensure everyone is on the same page
- Technical documentation should be written so that it's accessible to multiple categories of people, your target audience needs to be taken into account
- How to Create Technical Documentation with Examples Caution: blog by a company trying to sell a product
- README files
- Used to have setup instructions for how to run a script/program/app including everything that needs to be installed and dependencies that are required
- README files are used commonly so that everyone knows where to look for the instructions, sometimes included by default if using a tool to help setup the script/program/app
- README is the first place people look, so the target audience should be someone that's never encountered your script/program/app before and knows nothing
- README files are a good general overview, but there are other common files that can be included such as AUTHORS, CHANGELOG and LICENCE
- Markdown is popular to use for documentation because it is easy to learn, and includes the ability to visually illustrate things, even if it doesn't get rendered correctly it's obvious what the structure is
- There are variants of Markdown, sometimes companies will extend the standard to include extras such as Discord, GitHub and Reddit
- Comments in your code
- Different people have different opinions, you will likely form your own opinion and it will likely change as you gain experience, you're likely to get conflicting advice
- The code is the documentation
- Code documentation is just some helpful pointers through the codebase
- Everything in the code should have documentation
- Header comments before the code can include authors, variable and function names, or even instructions on code running/usage opinions vary on if this is the right way to go
- Header comments can also be block comments before each function with description and use cases
- Names are also documentation, function, variable and class names can be used as code documentation
- There are some naming conventions that are out there sometimes by language or by programmer, or by philosophy. Such as MyVariable, myVariable, my_variable, MYVARIABLE, my-variable, or My-Variable
- Unit tests and executable examples can be another form of documentation for code
- Wikipedia on Code comments Wikipedia is user edited, code comments have philosophies and fashions just like everything else
- Coding and Comment Style by MIT Communication Lab
- Accessibility
- You should write your documentation keeping others in mind, this can include things like:
- What if someone is colorblind
- What if someone has low vision
- What if someone uses a screen reader
- Screenshots are helpful but should not be the only source of information
- Keeping a document accessible is better for everyone, example: subtitles and who uses them
- Making your documentation accessible makes it better for everyone
- You don't know who will read your documentation, don't make assumptions, don't make someone ask for special treatment, make it accessible by default
- Accessible Documents for Section 508 Standards
- Accessible documents by Harvard University
- AI and documentation, README and comments
- AI can be helpful for documentation, you can use AI to do things like organize your documentation and thoughts, help start to turn your documentation into other formats, or even just to bounce ideas off of
- AI can be helpful with things like starting scripts/programs/apps to include best practices and ensuring you have a start on each file/package you need
- AI can help generate the start of documentation for things that are badly documented, or not documented at all
- AI can help you keep your documents up to date, and check the validity of some types of documentation such as checking unit tests or running scripts regularly (think cron job but better)
- If an AI is aware of the documentation, it can use the information or spit back chunks of information, based on the questions you're asking
- Generative AI and documentation Caution: By a company trying to sell you AI
- Caution: junk in, junk out, documentation quality matters a lot with an AI
- WARNING: AI is not perfect, AI hallucinates, don't just blindly assume it worked, check everything, read/listen to what the AI gives you
- Software suggestions
- Version Control
- Example: GitHub
- Used to keep track of changes, have a lot of who changed what with a short note as to why, allows you to roll back, ensures there is a consistent record including time stamps, signatures, and authentication
- Wikis
- Example: Confluence
- Used to have multiple people be able to edit and improve the document, supposed to make sure there is one source of truth in the documentation and makes organization easier
- Issue trackers
Suggested Activities and Discussion Topics
- Activity: Read through this first example and then this second example of documentation written by an AI. And then answer the following questions. This should take about 30–45 minutes.
- Define the Audience and Tone for each
- Compare how they handle dense material. WHich one does it better? Why?
- How did they do on visual aids? Were you able to follow what was going on?
- Is either one considered Accessible? Why or why not?
- Evaluate this third example where does it fall on the good vs bad scale?
- What about this one? Is this better? Worse? What's wrong with it? Be specific!
- Activity: Listen to This Podcast That was created using AI from these materials. Transcript for the Podcast What are your thoughts? Did the AI do a good job representing the materials? Did you find any mistakes? If you happen to speak Spanish, what do you think of the AI translation to Spanish version of the Podcast? Did the AI do a good job? Bad job? This should take about 20–25 minutes.
- Activity: Go through This AI generated study guide, what do you think? Did it capture the materials well? Do you know all the vocab used? What do you think is missing?
- Activity: Go through this AI-generated key terms list for this module. How many of the terms did you already know? Were there any definitions you would update or expand based on the lecture notes? Did the AI miss any important terms? This should take about 10–15 minutes.
- Activity: Go through either Option 1 or Option 2 and fix it up so it meets best practices and is improved. COnsider some places start that could be fixing the numbered lists, bullet points, and/or appropriate headings, adding in a overview or roadmap, and changing the tone of the documentation to be clear and professional. This should take about 30–45 minutes.
- Activity: Take this intentionally badly commented code and fix it so that it's well documented. SOme things to try changing include variable and function names, comments already there, and adding in a header comment. This should take about 30–45 minutes.
- Activity: Pair up and create documentation for something you're both interested in. This could be anything from how to play a video game or board game, or instructions for a recipe you both are interested in. Discuss how you can organize your document, what it should have, how long it should be, what level of detail is required and who the target market it. Now switch documentation with another pair and take notes on what they did, think of at least 2 specific things you think they did well, and 2 specific suggestions to make their documentation better. This should take about 45–60 minutes.
- Activity: Choose an AI tool of your choice such as ChatGPT, Gemini, or Claude. Write a short function of 5–10 lines in any language you have used, intentionally using vague or confusing variable and function names (for example,
def x(a, b)ortemp2 = stuff * thing). Paste your code into the AI and ask it to suggest better names and add an appropriate comment. Then evaluate the AI's suggestions: Did it correctly understand what your code does? Are the suggested names actually clearer? Did it add any comments that were obvious or unhelpful? What would you change? This should take about 5–10 minutes. - Activity: Find an open source project on GitHub. It can be anything from a small personal project to a well-known library. Evaluate its README file using the criteria from this module: Does it explain what the project does? Does it include setup instructions? Is it clear about dependencies and how to run it? Does it assume too much prior knowledge? Write a short evaluation identifying two things it does well and two specific improvements that would make it more useful to someone encountering the project for the first time. This should take about 20–30 minutes.
- Activity: Write a README file for a project you have worked on, such as a class assignment, a personal script, or even a made-up project. Include at minimum: a description of what it does, how to set it up, how to run it, and any known limitations. Then ask someone who has not seen the project to try to follow the setup instructions without asking you any questions. Observe where they get stuck. What did you leave out that felt obvious to you but was not obvious to them? What would you change? This should take about 30–45 minutes.
- Discussion: Think about a time when bad documentation, or no documentation at all, caused you a real problem. This could be in a class project, at work, or while trying to use software someone else wrote. What specifically was missing? What would good documentation have looked like in that situation, and how much time or frustration would it have saved you?
- Discussion: Documentation is often described as the part of a project that everyone agrees is important but almost no one wants to do. Why do you think that is? What would need to change in workflow, tooling, culture, or accountability to make documentation something that gets done consistently rather than added at the end as an afterthought, or skipped entirely? Have you ever been on a team or in a class where documentation actually happened? What made that different?
Related modules you might find useful
Would you like to see some more How tos? See more How tos