How To Write Good Documentation

Writing good documentation starts with what you are solving. You have to include why this is important and why should the user care. I write documentation so that I really learn what I am doing. Missing crucial points will hinder my ability to understand the concepts that I writing or programming. People also write documentation to teach other people about skills and concepts that they have learned.

Staring out with software documentation it is important to include 6 important details that is outlined in the article The Art of Writing Good Documentation. These 6 details are

• context of the problem being solved
• broad idea of the changes you are making
• decisions that were made
• consequences of actions
• the history of the software
• (most important) Things that will hurt you if you forget them. Once you illustrate and convey these ideas you will have documentation that you can use as a reference.

On the technical side documentation is mostly written in markdown which is an easy file type that can manipulate how text is presented. Additionally you can write markdown documentation in an editor like Visual Studio Code, notepad, or really any text editor that takes markdown. A great part about markdown is that when you use an app to help write notes and documentation, all your data is in a folder and you can switch apps whenever you would like. For now, I use Obsidian as my markdown editor because it makes every thing every easy to create with tabs and whatnot. Also, I like to use images as a thumbnail for my documentation and to do that I drag and drop the image onto the document that I am writing in. It will add the image in and I just put all of those images into a folder called "Photos".

Very Important that you press Ctrl + S to save all your work so that you don't lose it!!!

Markdown has many annotation or syntax types that manipulate the text. This is being provide by this Basic Syntax | Markdown Guide.To display the syntax and not for it to preview, add a backslash beforehand. Do Not use the backslash in the other syntax otherwise it will only display the syntax and not preview. To imbed quotes like I did above, use [Anchor Text](URL). To italic something add an asterisk on either side of the text *italic*. For bold add a double asterisk on either side **bold**. For both write three asterisk on either side ***both***.

• Lists are - item
• Headers # Title #title
• Heading # heading (h1) /## is h2 and so on
• Blockquotes is > blockquote
• Code blocks `code` code There is also many more like email footers, blockquote imbeds and other cool headings you can do markdown but these are easy to get started. You can see more in the linked article.