What to write - Jacob Kaplan-MossTech docs can take a bunch of different forms ranging from high-level<br>overviews, to step-by-step walkthroughs, to auto-generated API<br>documentation. Unfortunately, no single format works for all users;<br>there’s huge differences in the way that people learn, so a<br>well-documented project needs to provide many different forms of<br>documentation.
At a high level, you can break down the different types of documentation<br>you need to provide into three different formats:<br>…">Tech docs can take a bunch of different forms ranging from high-level<br>overviews, to step-by-step walkthroughs, to auto-generated API<br>documentation. Unfortunately, no single format works for all users;<br>there’s huge differences in the way that people learn, so a<br>well-documented project needs to provide many different forms of<br>documentation.
At a high level, you can break down the different types of documentation<br>you need to provide into three different formats:<br>…">Tech docs can take a bunch of different forms ranging from high-level<br>overviews, to step-by-step walkthroughs, to auto-generated API<br>documentation. Unfortunately, no single format works for all users;<br>there’s huge differences in the way that people learn, so a<br>well-documented project needs to provide many different forms of<br>documentation.
At a high level, you can break down the different types of documentation<br>you need to provide into three different formats:<br>…">Tech docs can take a bunch of different forms ranging from high-level<br>overviews, to step-by-step walkthroughs, to auto-generated API<br>documentation. Unfortunately, no single format works for all users;<br>there’s huge differences in the way that people learn, so a<br>well-documented project needs to provide many different forms of<br>documentation.
At a high level, you can break down the different types of documentation<br>you need to provide into three different formats:<br>…"><br>Writing Great Documentation:<br>What to write<br>I wrote this post in 2009, more than 16 years ago.<br>It may be very out of date, partially or totally incorrect. I may even no longer agree<br>with this, or might approach things differently if I wrote this post today. I rarely edit<br>posts after writing them, but if I have there'll be a note at the bottom about what<br>I changed and why. If something in this post is actively harmful or dangerous please get in<br>touch and I'll fix it.<br>Tech docs can take a bunch of different forms ranging from high-level<br>overviews, to step-by-step walkthroughs, to auto-generated API<br>documentation. Unfortunately, no single format works for all users;<br>there’s huge differences in the way that people learn, so a<br>well-documented project needs to provide many different forms of<br>documentation.<br>At a high level, you can break down the different types of documentation<br>you need to provide into three different formats:<br>step-by-step tutorials,<br>overviews and topical guides to the various conceptual areas of<br>your project, and<br>low-level, deep-dive reference material.
Let’s look at each in turn.<br>Tutorials<br>Good tutorials are a must as they’re usually the first thing someone<br>sees when trying out a new piece of tech. First impressions are<br>incredibly important: that rush of success as you work through a good<br>tutorial will likely color your future opinions about the project.<br>Django’s tutorial is frankly a bit musty at this point and is probably<br>due for at least a light refresh, but it hits all the important points.<br>A good tutorial should:<br>Be quick. At some conference or another I heard someone – I<br>think it was Kathy Sierra – say<br>that, as a rule of thumb, a new user should be able to experience<br>success within thirty minutes. That’s a great rule: thirty minutes<br>is nothing – think “half a lunch hour.” If your project can give<br>new users the warm fuzzies that quickly, they’ll come away<br>wondering about all the awesome successes a deeper dive might<br>give.
Be easy. Remember: you want success to be the outcome of the<br>tutorial. This means you need to playtest the tutorial under all<br>sorts of different circumstances, making sure that it always works<br>(even on Windows).
But not too easy. There’s always going to be a class of users<br>who aren’t really qualified to use your project. Someone who’s<br>never written any code before isn’t going to get very far with<br>Django; those types of users should fail quickly. Don’t get them<br>through the tutorial only to run into a wall later on.<br>Another similar anti-pattern is glossing over bad choices made in<br>the interest of expediency. Django’s tutorial makes this mistake:<br>we gloss over the project/app distinction in a way that bites<br>users later on. (It’ll get fixed soon, I promise!)<br>The best way of thinking about a tutorial’s ease is that it’s the<br>on-ramp onto your project’s learning curve. This means the slope<br>can be more gradual than later tasks, but no so much so that<br>things suddenly get much much...