User:Mooeypoo/Draft:Documentation Norms

''This is a draft. Feel free to discuss or edit as we agree on how this should look like for the team.''

Purpose
This document exists to help us work together and collaborate on our tasks, projects and code. It’s meant to encourage and enable collaborative work and establish a good practice for maintainability for the future on anything we work on.

Many of the projects we touch on are being worked on by other people and by volunteers -- if we establish good communication and documentation guidelines, we can encourage more participation and a solid maintainable way for others, especially volunteers, to pick up where we left off.

Assumptions
While we work, we all hold these assumptions that will help encourage good documentation:

Documentation isn’t meant to make sure we do our work -- it’s to make sure we can collaborate together!
We should communicate so we understand where challenges came up, assess the impact to the users or architecture, and recognize best practices.

Task and commit documentation should enable a teammate or volunteer to pick up the work
... and continue where you left off as quickly and seamlessly as possible

Anyone looking at a task or a commit should understand the main points of what is going on, and recognize any specific challenges that came up, or any outliers that we encountered

We build on our experience!
Decisions that have good reasoning help us understand how to continue to do things in the future; what works, what doesn’t work, and what we should try and change later. These things are best when flagged, even if the prioritization to fix them is decided to be later.

Don't assume something is obvious
We work on different codebases and products and have varied experiences in different areas of the code. Something obvious to you can be completely baffling to another. Don’t assume -- point it out and explain.

If something looks "off" -- write a comment!
We all make decisions in our code, and they may sometimes look different than norms or they may raise questions. Documenting inline means anyone reviewing the code -- and anyone looking at the code in the future -- will understand why a decision to use one method instead of another was chosen. It will also make it easier for us to know if we should change a piece of code or leave it be.

Code work (and related tasks) should be as focused and standalone as possible
A commit should concentrate on a straight-forward change, as much as possible. If changes occur inside the commit that are logically different, consider splitting to another dependent commit. For example: Working on a commit that changes a method made us realize that we need to fix linting or correct unrelated messages, these changes should be in a separate commit. That way, reviews are easier and faster -- standalone changes can be merged quicker, while the more robust commit can be scrutinized separately.

When submitting for review, assume you’ll never touch this code again
The project might be deprioritized, you might go on vacation, there may be an unforeseen urgent bug you must turn your attention to and whatever it is you’re working on now, is put to the side.

"Hacks" should be rare, but when they happen -- explain them clearly
Documenting "hacky" decisions serves to remind us the reason of why we went this way, but also serves as a red flag in the code. If a piece is slowly being filled with "hack" comment, we can immediately see we should refactor that code or rethink our strategy.

Discussions on general concepts are best done in the ticket
If during code-review there are discussions about general concepts -- implementation strategy, alternative approaches, or change of direction -- that deserve hashing out, it’s best to discuss in the ticket, and when a decision is made, redo the commit and if needed, change the commit message accordingly.

In the ticket, explain what happened for the non-technical reader
Assume that every page your write is "Page 1" for the reader, where the reader knows nothing other than what they read in your explanation. Link to resources as needed, explain technical decisions, potential pitfalls or side effects, and make sure the reader (be it product manager or fellow code reviewer) can understand quickly what the problem/feature is, how to reproduce it, and how to check the new code’s behavior.

Make sure reproduction steps, or testing steps (and any caveats to them) are clearly laid out
We work on multiple products in various contexts and, sometimes, platforms. Make sure reproduction steps are available to test the commit you’re working on. These steps should be reproducible by another Engineer and by anyone doing QA, depending on the feature or bug. Make sure these exist, and are up to date.

Document repeated code in extended classes
When we copy code from external classes or libraries (either the parent or any other,) document clearly where the code came from, and point to where there are changes from the original. If the original code changed and we need to change it locally, this helps us adapt with minimal hassle. (It’s also a good way to have a red flag about whether this should be generally avoided)

Open questions

 * Where do we document, and what? What goes on Phabricator? What goes in commit, code comments, or what goes on wiki?
 * What does "hack" mean? Do we have a normalized definition of "hack" solution?