Inca Best Practices

Committing to GitHub

Committing to GitHub is the only way to show everyone what you are working on. It is important to wire updates every time you did something, however small it is. It allows others not only appreciate all the work you are doing, but also helps them keep you on the right track. If they see no updates from you in the past 24hr, people will assume you took a day off.

Communicating

If it’s not in GitHub, it never happened We keep all substantive conversations and discussions on GitHub, so we have the entire history of our projects in one place. All arrangements made outside of GitHub (Google Meet, Inca Water Cooler, email, etc.) are to be duplicated on GitHub. It is also essential that you reply promptly to all requests on GitHub. Generally, we are against one-on-one conversations and ask you to invite other people using Google Calendar or Inca Water Cooler chat channels. Administrative, personal, and security-sensitive conversations are an exception.

Structure One way to show other team members you value their time is to add more structure to your communication. Provide context, make lists, link issues, add labels, use milestones… Demonstrate you did research and organized your thoughts before involving other people in your issues. It’s not their job to figure out why you are doing something and whether it makes sense at all.

Have a plan However bad it might be. It’s much better to come up with a numbered steps plan and ask people to help you to improve it than make them guess or create one for you.

We expect to see your comments and commits every day, however small they are!

4-Step Principle

Follow these 4 steps whenever you approach a new task. It is important to get to the MVP stage as soon as possible and iterate often!

1. Functional Requirements (business goals)
2. Technical Requirements (what it takes to achieve business goals)
3. Minimum Viable Product (MVP)
4. Small Iterations

MVP

Get to an MVP as quickly as possible. A rough mock-up with missing features is good enough. Start with building everything yourself and involve relevant colleagues as needed, relying on them only to improve specific parts of the product, rather than solving abstract problems. The idea is to have a full skeleton from day one to see the product as a whole. It will help you identify bottlenecks early, involve the right people, and provision any additional resources in advance. A working MVP will also allow you to leverage task parallelization - multiple people can start working on improving different parts independently. Don’t expect your tasks to go as planned if you haven’t prototyped them. The worst thing that can happen is you discovering surprises in the last piece of puzzle the day before the deadline.

Priorities

Rules, guidelines, principles, people, they all have influence on what you do and how you do it. How do you figure out who to listen to and what to prioritize? Here’s the list of things to consider in the order of their importance:

1. professional ethics and common sense
2. company values, strategy, and goals
3. your bosses and personal responsibilities/priorities
4. relevant clients and colleagues
5. everything/everyone else

SWAT vs Gunslingers vs Police Officers

SWAT teams show up all together in full gear no matter what. They bring enough weapons and ammo to occupy a small village. They bust doors and windows without checking if they are unlocked.They don’t care how much it costs them to arrest a pothead or to repair the damage they cause doing it.

Gunslingers think they can shoot everyone in the village by themselves. They rarely have a plan and rely on their marksmanship skills. They don’t communicate with anyone and often shoot random bystanders. Gunslingers rarely last long - they either get shot or fired.

Police officers always follow the plan and tell the dispatcher if they want to investigate something off the beaten path. They update their dispatcher on any developments. Police officers use common sense and department priorities when choosing the car to pull over. They do their research and run the license plate before approaching the vehicle. Police officers don’t write tickets together, but they often request backup to have someone cover them if the situation escalates and help each other without getting in the crossfire. Police officers are also mindful of the costs and call for air support only in critical situations. Their most valuable quality is the ability to follow rules and guidelines in stressful situations.

Always default to the police officer approach.

Issue Guidelines

Issues are a core part of the development process. Always create an issue for things you work on. If it is worth spending time on since that enables other people to see your work in real time and intervene if something doesn’t look right. You can always edit the description or close it when the problem changed to something different or was solved.

Issues need to have at least the following:

1. Brief description with necessary steps to close the issue, relevant links, associated issues and an estimated due date.
2. Assignee. It’s okay to have multiple people involved in the issue, but pick one assignee, who will act as the lead person. @ other relevant people in the issue description and clearly state their role.
3. Relevant labels and milestones. Mandatory labels: status, priority. For the data requests issues, make sure to add the “data request” label
4. For managers and people involved in the task, make sure it is also added to your/their projectboard.

Update your issues

You must update your issues with:

• All notes from meetings
  • Who was included
  • What was discussed
• Updates on work you are doing
  • Merge requests associated
  • Problems you are working through
  • When things are completed
  • Methods/techniques you are using or considering
• Questions or clarifications (tell people if you are stuck or unsure of how to proceed)
• Labels, assignee, or steps

Do not leave issues idle for a long time; they should be actionable and realistic. Keep them updated, however small the progress is. Every time you do something, successfully or not, leave a quick comment for others to see progress or the lack of thereof. If you just want to have a brainstorming issue and don’t attach it to any active client or a milestone, GitHub has Discussion tab for you to use.

If you are assigned to an issue but don’t have time to work on it, ask for help, add status::on hold tag, or assign it to someone else. If you don’t have time to do something let people know instead of having it linger. You can use the text: “I have other priorities and can’t help with this” or “I can complete this on May 25, please let me know if that is OK”.

When someone asks about a task, give back a deadline. Answers like: ‘will do’, ‘OK’, ‘it is on my todo list’ are not helpful. If it is an easy one, it is better to spend 2 minutes doing it and forget about it. If it might take time, you need to figure out when you’ll do it, by returning that information the other person might decide to solve it in another way if it takes too long.

When you complete the issue, add a quick comment and assign the status - done label so the person who opened it can double-check everything and close it. Unless you are the one who opened it, don’t close the issue yourself.

Deadlines

Always keep an eye on the due dates for project milestones and issues. It can alway be found in the milestone/issue description. It is important to set realistic deadlines and discuss them with the team.

• If you are the one creating a milestone, always follow our SMART guidelines and assign a due date, even when you are not sure how long it will take to complete.
• If you are working on an issue and are afraid you won’t be able to finish by the milestone due date, let the issue creator know right away. It will allow them to pull additional resources to help you or adjust their roadmap.
• If you want to change the milestone deadline, make sure to leave a comment on it in a milestone progress tracker.

Outsourcing Work

Our company promotes outsourcing of well-defined tasks in order to quickly and cheaply accomplish goals. Work can be outsourced in two main ways: (1) requesting that we pay for a service or product to accomplish the task, or (2) requesting the creation of a “bounty issue.” To request that an existing service or product is used, notify the project manager directly in the relevant issue, or communicate your thoughts within the appropriate Inca Water Cooler chat channel. To learn how to initiate a bounty project please see the Challenge Program Documentation