You can add new articles to either the Hacker Book or the Program Book.
When adding a new article, make sure you format the file such that the first several lines of the markdown file are:
---
title: "Title of the Article"
path: "/hackers/title-of-the-article.html"
id: "hackers/title-of-the-article"
---When adding a new article to the program book, make sure you format the file such that the first several lines of the markdown file are:
---
title: "Title of the Article"
path: "/organizations/title-of-the-article.html"
id: "organizations/title-of-the-article"
---You can also add a changelog entry for a new month that isn't listed on the changelog yet. To add a changelog entry for a new month, make sure you format the file such that the first several lines of the markdown file are:
---
title: "Month Year"
path: "/changelog/[year]/[month]"
date: "year-month number"
---Example:
---
title: "November 2016"
path: "/changelog/2016/November"
date: "2016-11"
---| How do I... | Answer |
|---|---|
| Add a link to a page within the docs site of the same book | [Start H1 Response](start-h1-response.html) or [Start H1 Bounty](start-h1-bounty.html). |
| Add a link to a page within the docs site to an article in another book | [Start H1 Bounty](/organizations/start-h1-bounty.html) |
| Add an image |  |
| Reference the HackerOne blog link | Use https://www.hackerone.com/blog not www.hackerone.com/blog |
We use active voice at HackerOne as active voice is more personal and engaging vs. passive voice. In active voice, the subject does or acts upon the verb, while in passive voice, the subject is being acted upon.
| Active Voice (Yes, please use this!) | Passive Voice (Steer away from this) |
|---|---|
| Click the link to search | The link should be clicked when you're ready to search for an article. |
| The hacker reported the vulnerability. | The vulnerability was reported by the hacker. |
| The security team triaged the report. | The report was triaged by the security team. |
In order to convey a personal and less formal voice, it's best to use contractions instead of the formal non-contractions.
| Contraction - (Yes, please use this!) | Non-Contracted Phrases (Steer away from this) |
|---|---|
| can't | cannot |
| don't | do not |
| won't | will not |
| it's | it is |
| they're | they are |
| we've | we have |
| you're | you are |
There are some words that can be used with multiple spellings. In order to keep consistency, we need to agree on which spelling to go with.
| Yes | No |
|---|---|
| checkbox | check box |
| double-check | double check (this is a noun) |
For numbers that are greater than 0, use the numerical number instead of spelling it out. For 0, spell out the word.
| Yes | No |
|---|---|
| Zero | 0 |
| There are 2 vulnerabilities in that program. | There are two vulnerabilities in that program. |
| The program has 3 valid reports. | The program has three valid reports. |
The purpose of error messages isn’t to tell users that they’ve made a mistake. The goal is to give them instructions with how to fix an error.
| Good Error Message | Bad Error Message |
|---|---|
| Enter a date that isn’t before the reported date. | The resolved date can’t be before the reported date. |
| Sorry, we couldn’t find an account with that username. Can we help you recover your username? | That username doesn’t exist. |
| Sorry, that password isn’t right. We can help you recover your password. | Wrong password. |
| Enter a valid email address to use as your Apple ID. | The email address entered is invalid. |
| That account doesn’t exist. Enter a different account or create a new one. | Sign-in unsuccessful. Please try again. |