Throughout daily work as a developer, designer, or any field that involves long-form work, you’ll need to learn some form of documentation to keep track of your thoughts or to let someone else know what your thoughts were. For our purposes at Wide Open Technologies, as a collection of designers and developers, we use documentation for those purposes and for a variety of other reasons.
Code Commenting
For a developer, the simplest and most non-invasive way to write documentation is through code comments. Commenting your source code directly serves no purpose to your runtime, functions, etc., it is strictly for your benefit and for whoever may come after you into that source code. Even better, since commenting is completely harmless and is written alongside your code you can code like you would and comment as you think things through.
/**
* Tell me my name
*/
sayMyName = function(name){
console.log(‘My name is ‘ + name); //log the name
}The example above is of a simple JavaScript function that will log the name that you supply the function say MyName. Above the function, I have a block comment to tell me the gist of what the function will do. Block comments can be as simple as the gist or can be expanded further to include parameters, returns, and anything else that may be important to the function. In addition to the block comment, I have an inline comment //log the name which is specific to just that line. Inline comments are a great way of commenting long chains of actions without cluttering your source code. Regardless of where you are in your development career, code commenting is a day one skill that will stick with you forever. Creating good documentation through commenting will keep you effective and confident about what you create. Code commenting isn’t just good for you, it’s good for whoever comes behind you, good for your clients, and good for your company (or yourself). Just remember:
Always Comment your Code like the next person who will read it is an axe murderer, knows where you live, and holds a grudge against you.
Code Styling
Code Styling is an underappreciated and overlooked aspect of code development but is an excellent form of documentation on its own. Conceptually, the idea behind code styling is that if everyone follows the same conventions for naming variables, functions, classes, etc. and follows the same conventions for indentation, bracket treatment, and white space then everyone’s code will be indistinguishable and hence readable by whoever is on the project. Code styling is perfect for large projects where multiple may need to access multiple resources at the same time as it favors conventions over configuration and, since everyone’s code will be equally readable, means that even if something isn’t perfectly commented/documented it will at least be easily traceable for anyone who is part of the project. So be consistent and people will take notice – making your code partially self-documenting and much easier to understand. Personally, I write a lot of JavaScript (a lot) and follow this code standard very closely: https://nodeguide.com/style.html.
Wikis
Wikis are commonly included with many project management applications and are a great way to create public or private facing documentation without the need to know code. Style Guides are perfect for wikis as they would be in a centralized place and could be accessed without needing to access source code, like Code Commenting or Code Styling. When creating wikis, it’s important to keep content digestible and to the point. The quicker I can get the answers I need the better. This applies to structure as well. Many wikis are based on a page->subpage structure and using that hierarchy to keep your documentation inflow is a benefit to your users and a benefit to you, the maintainer, if there is a need to update documentation later. Wikis are a great place to put complex business logic and application setup instructions. Better instructions and documentation = fewer questions about what does what and how later on. Some examples of good open-source wikis:
- https://github.com/d3/d3/wiki
- https://github.com/Netflix/Hystrix/wiki
- https://github.com/guard/guard/wiki
These wikis are maintained, informative, and easily navigable – the epitome of what a good wiki should be. Use those as examples and you’ll go far.
So what should I document?
I’m so glad you asked: everything. Seriously! From code functionality to business rules, to server setups, to Photoshop files – anything that you learned and need to reference more than once needs to be documented somehow. Anything that you learned and someone else would need to know needs to be documented. Anything that you learned should, in general, be documented. Documentation is not the realm for code junkies to brag about what they did behind the scenes or shoot potshots at each other, and documentation is not a “not my job” situation. Documentation is for everyone to write because everyone benefits from it. Writing good documentation is kind of like remembering something better by writing it down. Sure, you heard the thing and will remember the thing, but writing the thing will make the thing that much easier to remember because now you are associating the thing with your hand movement – and that’s the thing, writing code comments, keeping well-styled code, and maintaining informative wikis will help you, the creators, remember what you created that much easier.
