Documentation Protocol

##Why Documentation? When there is such a large project such as tempo, the project inevitably becomes an amalgamation of code, with team members contributing bits and pieces of code to every files here and there. All too often, team member A will tackle a difficult feature X and come up with a solution. Team member B will then be assigned an enhancement to issue X, and then have to grasp the logic of member A. Maybe a few months later, member B will return to feature X, and forget exactly what was happening with that feature, and have to relearn everything. In the worst case, team member A leaves the team for whatever reason, and then truly nobody understands that code. Nobody wants to touch that piece of code, fearing that they will break the feature, and with enough of these instances, the project becomes a nightmare to maintain.

In-code comments can only go so far; it's hard to navigate and it often just makes the project files much larger than they need to be. Documentation is an investment that should pay off over time. It should make code ramp-up more efficient, which is one of the most time consuming portions of working on team projects.

With that said, it's definitely possible to over-document, so use your best judgment to document what is necessary. Code should be still written as readably as possible, but there are always functions that are intrinsically complex, so documentation should cover those areas. Hopefully, this will be less painful with the establishment of clear guidelines of what and how to document.

##Structural Guidelines

There will be a page for each of tempo's complex/unique features.

The general rule of thumb is that if you are given an issue that ends up becoming difficult and requires a deep technical dive into complex and esoteric code, instead of figuring it out, completing your issue, and then forgetting about the logic that you grasped to complete the issue, we will add documentation as a step. This way, code/issue ramp up and hand-off should be much faster.

Spotify Integration - overview of the configuration

Facebook Integration - overview of the configuration

PostView - how hits are detected, the different forms taken

Pinning - when/where/how it pins (may decide to get rid of this feature altogether)

PlayerTableViewController - class attributes/properties, how attributes are inherited by FeedTableViewController, LikedTableViewController, etc.

###A basic page should have these sections:

• Overview - brief summary of the feature being described, and possible intricacies
• Project Files - if there is a file that is the main focus, feel free to devote a section to it (ex. PostView.swift for the PostView feature). For each of these, create a sub-section. Otherwise, if you feel like the file isn't too hard to understand, just list it for reference. This should get rid of the chore of flipping through each file in the project to find where something specific is located.
• Current State - no feature is ever fully complete, note whether there are certain bugs, enhancements to be made, anything blocking the development of the feature, etc.
• External Sources - Any other sources that you may have used to implement the feature.

Other than those points, feel free to add whatever is necessary to document the feature well.

##Style Guidelines As this documentation grows, it's important to try to keep a consistent style guideline, for easier readability.

• Sections should be h2 size (prefix with ##)
• Sub-sections should be h3 size (prefix with ###), and if they are a file name, make it an inline code block
• Any code, keywords, etc. should be marked up as a code block (indent) or inline code (wrap with backticks)
• Avoid putting long code snippets in the documentation, as its prone to constant change, which then leads to having to update the documentation once more. Short, necessary code snippets should be fine. As a rule of thumb, it's generally better to try to explain with plain English and images.
• Diagrams/screenshot as necessary to make it easy to show what you are talking about