{"id":98,"date":"2020-07-23T16:39:54","date_gmt":"2020-07-23T16:39:54","guid":{"rendered":"https:\/\/courses.lumenlearning.com\/suny-esc-technicalwriting\/?post_type=chapter&p=98"},"modified":"2020-11-12T19:18:09","modified_gmt":"2020-11-12T19:18:09","slug":"virtual-presentations","status":"publish","type":"chapter","link":"https:\/\/courses.lumenlearning.com\/suny-esc-technicalwriting\/chapter\/virtual-presentations\/","title":{"raw":"Computer Code Documentation","rendered":"Computer Code Documentation"},"content":{"raw":"
\r\n
\r\n\r\nWhen you look back on code that you wrote six months ago, you may or may not remember why you did things in a certain way. Documentation allows you to transfer the\u00a0why<\/em>\u00a0behind code. Much in the same way code comments explain the\u00a0why<\/em>, and not the\u00a0how<\/em>, documentation serves the same purpose.\r\n

Importance of Well-Written Documentation<\/h2>\r\nThere are many reasons why it's important for you, as an IT professional, to apply good technical writing practices to writing code. Well-written documentation:\r\n\r\n<\/div>\r\n
\r\n

Enhances Usability<\/h3>\r\n\"\"You have written a piece of code, and released it into the world. You have done this because you think that others might find it useful. However, people need to understand why your code might be useful for them, before they decide to use it. Documentation tells people that this project is for them. If people don\u2019t know why your project exists,they won\u2019t use it. If people can\u2019t figure out how to install your code, they won\u2019t use it. If people can\u2019t figure out how to use your code, they won\u2019t use it. There are a small number of people who will figure things out and use your code, but that is a small number compared to people who will use your code when properly documented.\r\n\r\n<\/div>\r\n
\r\n

Contributes to your Professional Community<\/h3>\r\nOpen source is this magical thing, right? You release code, and the code gnomes come and make it better for you. Not quite. There are lots of ways that open source is amazing, but it doesn\u2019t exist outside the laws of physics. You have to put work in, to get work out. You only get contributions after you have put in a lot of work. You only get contributions after you have users. You only get contributions after you have documentation. Documentation provides a platform for your first contributions. A lot of people have never contributed before, and documentation changes are a lot less scary than code changes. If you don\u2019t have documentation, you will miss out on a whole class of contributors.\r\n\r\n<\/div>\r\n
\r\n

Strengthens your code<\/h3>\r\nIt\u2019s really easy to have an idea in your head that sounds perfect, but the act of putting words to paper requires a distillation of thought that may not be so easy. Writing documentation improves the design of your code. Talking through your API and design decisions on paper allows you to think about them in a more formalized way. A nice side effect is that it allows people to contribute code that follows your original intentions as well.\r\n\r\n<\/div>\r\n
\r\n

Enhances your Writing Skills<\/h3>\r\nWriting documentation is a different form of writing than most people have experienced. Technical writing is an art that doesn\u2019t come naturally. Writing documentation will start you down the road to being a better technical writer, which is a useful skill to have as an IT professional. Writing also becomes easier over time. If you don\u2019t write for many months, it's a lot harder to start writing again. Keeping your projects documented will keep you writing at a reasonable cadence.\r\n\r\n<\/div>\r\n
\r\n

What to Write<\/h2>\r\nMake sure that you give your users all the information that they need, but not too much. First, you need to ask yourself who you\u2019re writing for. At first, you generally just need to appeal to two audiences, users and developers. Users are people who simply want to use your code, and don\u2019t care how it works. Developers are people who want to contribute back to your code.\r\n

README<\/h3>\r\nYour first steps in documentation should go into your README. Code hosting services will render your README into HTML automatically if you provide the proper extension. It is also the first interaction that most users will have with your project. So having a solid README will serve your project well. Some people even go as far as to\u00a0start your project with a README<\/a>\r\n
\r\n

basic example<\/h3>\r\n
\r\n
\r\n
\r\n\"\"<\/span>\r\n<\/pre>\r\n<\/div>\r\n<\/div>\r\nThis will render into a header, with a list underneath it. The URLs will be hyperlinked automatically. It\u2019s easy to write, still makes sense as plain text, and renders nicely into HTML.\r\n\r\n<\/div>\r\n
\r\n
Explain the Problem your Project Solves<\/h3>\r\nA lot of people will come to your docs trying to figure out what exactly your project is. Someone will mention it, or they\u2019ll google a phrase randomly. You should explain what your project does and why it exists.\r\n\r\n<\/div>\r\n
\r\n
Provide a Small Code Example<\/h3>\r\nShow an example of what your project would normally be used for.\r\n\r\n<\/div>\r\n