Documentation 101

You just joined a startup and are expected to pick up the work of a previous member who has left. You’re looking through a mountain of their old files to try to understand their work, but their writing makes references to things that aren’t explained. You ask your teammates for help, but they can’t make sense of the docs, either.

Without any explanation provided about the work, the work itself is unusable. The team has little choice but to redo the previous person’s work from scratch, setting back the project by a quarter.

Months later, the startup has new management that wants to take the team’s work in a new direction. The proposals mean well, but will negate the work your team has spent so much time catching up on.

Luckily, you’ve been taking notes on your thought process and decisions. Everyone is able to get the management up to speed on the project history, and align on the startup’s future plans.

Documentation is about storytelling

Situations like the above happen in the real world more often than you'd think, and demonstrate the consequences of no or poor documentation. For a project to succeed, it’s not just about completing the work itself. The why, what you learned, and implications need to be explained, too. This is especially important in an environment like HfLA, where people are constantly coming and going, and acquired knowledge is easily lost.

That's all what documentation is - it's telling the story of the work. Good documentation has so many benefits:

• increases understanding and communication amongst current, former, and future team members
• reduces confusion, superfluous work, wasted time, mistakes, conflict, and hurt feelings
• tracks your accomplishments so you can read it weeks, months, or years later and understand it

You should document any work that you do for DS. After you’ve finished working on something, write a blurb about it while it’s still fresh in your mind. To get a sense of how detailed your documentation needs to be, imagine what a brand new team member might need to know to not be totally confused. Here's an example:

As part of the project to fix this feature, I worked on some new designs in my Figma sandbox (figma.c om/file/...?node-id=...) and referenced the research recommendations (drive.google.c om/file/d/...). After brainstorming with my teammate @___, I think we need to revisit how we think about this project and discuss it in the next general meeting, because we might not be serving our end users’ needs anymore, which has implications for our broader goals. The stakeholder stated in their interview that they want __, which we can still do despite the potential pivot...

Where to document

So you've told the story about your work - now you need to store the documentation so that it's findable and preserved for everyone.

GitHub is our main tool for storing documentation. If you're a non-developer and struggling to use it, that's normal - GitHub was never meant to be used by non-developers. HfLA teams are required to use it to help track the progress of projects. If it helps, remember that getting used to GitHub now will help better prepare you for your next job in tech, where companies follow similar practices using other project management tools like Asana, Monday, Jira, and Trello.

At the end of the day, GitHub is merely a tool to organize documentation. The quality of your storytelling is more important.

How GitHub organizes documentation

Each task that the team does is housed inside an issue. It's just a place where you tell the story of the work you did. You can add checklists to them and track how many action items you've completed.

All issues that this team has ever created will populate on the DS issue page.

We organize and filter issues in a few different ways:

By project board column

Issues can be organized in a Kanban-style project board, which just means that the issues appear as cards inside one of the board's columns:

1. backlog (to-do, not started yet)
2. in progress (being completed)
3. done (issue is done and closed)

Our team uses multiple project boards, since the columns can get cluttered fast. Our main project board contains most of our issues, while there is a separate board for onboarding and a separate board for documentation practices. You can access all project boards via the Projects page. If using the gray secondary navigation bar, you'll have to click Projects and then Projects again under Projects (beta).

(As of spring 2022, HfLA's official policy is to have new issue approval, ice box, and backlog as separate to-do columns, and blocked issues under a questions column. Due to DS team behavior and feedback we don't recommend having too many more columns than the 3 that the Kanban method originally intends. Additionally, having just 3 columns for all issues helps Github generate an accurate progress bar.)

By milestone

Think about the last to-do list you made. You might have written down a broad goal as the main “tier,” with tasks, and maybe mini-steps within those tasks:

• Goal
  • Task
    • Mini-step

In Github, the "goal" is the milestone. The “tasks” are the issues. If there are mini-steps, the team puts them in the comments of the issues:

• Milestone
  • Issue
    • Comments

All milestones can be found on the milestones page, which you can get to by clicking Milestones from the DS issues page.

(As of spring 2022, we don't recommend creating issues for "epics" - please use milestones to group tasks into larger goals.)

By label

Labels are colorful tags for issues. Since they can be very eye-catching to the point of distraction in the Kanban view, we try to reserve labels for broad categories.

Label category	Meaning
hourglass emoji ⏳ <# hrs	how long an issue will take to complete
bust silhouette emoji 👤	which team or role is responsible for the work
puzzle emoji 🧩-	the product feature that an issue is working on
exclamation !	high priority issues
question mark ?	issues that need help or review

Going back to the example of an individual issue, the sidebar contains all of the filters we talked about:

You can see a list of all labels on the labels page, which you can get to by clicking Labels on the DS issues page. Just ask first before you create or delete any labels.

Other documentation platforms

The other platforms we use are, frankly, more user-friendly for beginners than GitHub is. But in terms of documentation, these platforms are secondary to GitHub. If your work is located in one of these platforms, just make sure you return to GitHub to tell the story of your work.

Platform	Uses	Warnings
Google Drive	Collaborating in real-time, essay drafts or docs that are constantly updating. Stores detailed edit history	When sharing, paste the actual file link instead of folder links. When your team has finished a draft, paste the contents somewhere else. Folders are slow to load, and difficult to navigate if not nested well. If folders move or get deleted, the links break and a user will not have any context for where to go.
Slack	Quick updates, emergencies, or confidential topics.	Gets disorganized if there's a hodgepodge of messages and threads. In channels, reply to a message instead sending a new message when possible. Messages are automatically deleted after a few months, which is great for privacy but terrible for preservation of knowledge. Important messages to be referenced later need to be copied and pasted somewhere else
Figma	Referencing specific parts of a design or whiteboard, using comments, page names, group names, and frame names	Slow to load on computers. Hard to tell a longer story. Documentation is not findable in an infinite whiteboard and can get messy quickly.

Note about Agile and Scrum

When you move on to other tech companies, you might encounter the software development frameworks Agile and Scrum and the project management tool Jira. Unlike GitHub, Jira considers all tiers of tasks as "issues," and the tiers are Initiative, Epic, Story, and Subtask. This extra info is only here in case you notice HfLA volunteers using these terms.