Making a guide

Making Guide

Guides might seem like a boring proofreading task, but it is the exact opposite. It will help you:

• Connect with mentors across all Hack for LA projects
• Hone your communication skills
• Take you on a technical deep dive from your career subject area.
• Teach you about business documentation writing (which employers say is the hardest to find skill among perspective employees)

What is a Guide?

Hack for LA Guides are documents with step-by-step procedures for achieving a goal or task. We call these processes and practices.

Guides have examples from Hack for LA projects.

Some guides have templates.

Some Guides have many ways of achieving the goal Some guides have only one way of achieving the goal and are supposed to be very prescriptive:

Who writes Guides?

Are guides written by Experts?

No! Guides are written by volunteers like you, from all the Communities of Practice

In fact, the less you know about a process or practice, the better. Experts often miss explaining what seems obvious to them.

Why should you do it?

Helps you connect with other project leads that can provide mentorship & practice taking inventory

Where to start

GP: How to Gather Examples and Interview Teams

Finding Examples

We will teach you how to find the content in

• GitHub:
  • Wiki
  • Issues tab > filter by keyword
  • Project Board link cards
• Slack

How to get Mentors to talk to you

• Busy people who have their own work to do are sometimes hard to reach. We will teach you the winning soft skills that will make you successful at this task and in your career.
• We provide help with what questions will move the conversation forward.

Will I be able to finish the guide?

Sometimes guide issues are passed from volunteer to volunteer, with each new assignee moving it forward a little more.

But I really want to spend all my time coding!

There are lots of opportunities to code things (from classes, to boot camps, etc.).  There are very few opportunities to work directly with Senior Tech Leads on making instructions and documentation and then testing the instructions with real users (usually involves coding).  And getting that real world knowledge is a big part of being a successful coder.

Example

The Docker guide issue requires the person writing it to do some or all of the following:

• Survey all the teams using it, and determine how they are using it, and interview the tech leads to find the answers to questions such as:
  • Has Docker containerization helped the project onboard new developers or hindered that process, etc.
  • I see you use Docker in X way, which is different from other teams,  Can you look at this example and explain what the difference is?
  • Etc.  (You will figure out what questions to ask as go along)
• Write up guidance about how a Hack for LA software team could use it
• Ask some tech leads you interviewed to proofread it (we call that peer or mentor review).
• Find a Hack for LA software team that is interested in trying it out
• Have the person planning on trying it, use your guide and identify what it does not answer so that it can be improved

This Docker issue, has been worked on a bit by Sakari Salminiitty, who is a rising senior at Brentwood School, when he was here during the 2021 Summer Internship (summer interns both code and work on a guide).