You can add new articles to either the Hacker Book or the Organization Book.
All pull requests require approval before going live. New documents should be reviewed by the UX or Technical Writer before being approved.
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 |
Do not use abbreviations in our platform without spelling them out completely first. Your first mention should be the full word with the abbreviation in parenthesis. After that, you can use the abbreviation for all further mentions. Eg: HackerOne's Bug Bounty Program (BBP) is a public program. Please be mindful that not all BBPs are public.
Below are some common abbreviations used by HackerOne
| Abbreviation | Definition |
|---|---|
| 2FA | 2 Factor Authentication |
| API | Application Programming Interface |
| BBP | Bug Bounty Program |
| CTF | Capture The Flag |
| CVE | Common Vulnerabilities & Exposures |
| CVSS | Common Vulnerability Scoring System |
| MFA | Multi-Factor Authentication |
| SOC | Security Operations Center |
| VDP | Vulnerability Disclosure Program |
| XSS | Cross-Site Scripting |
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.
| This | NOT | That |
|---|---|---|
| cyberattack | NOT | cyber attack |
| engagement | NOT | program |
| organization | NOT | company |
| hacker-powered | NOT | hacker powered |
| internet | NOT | Internet |
| eBook | NOT | ebook or e-book |
| e-commerce | NOT | ecommerce (capitalized at the beginning of a sentence only) |
| pentest and pentesting as one word | NOT | pen test or pen testing |
| cybercriminal, bad actor, or malicious actor | NOT | criminal |
| hacker | NOT | researcher Exception: communication with government programs |
| malicious hacker | NOT | black hat |
| ethical hacker | NOT | white hat |
| checkbox | NOT | check box |
| double-check | NOT | 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. |
The preferred source of instructional embedded videos is the HackerOne YouTube channel and configured to be Unlisted. These should render on-page as an iframe with the following parameters:
<iframe id="ytplayer" type="text/html" width="640" height="360" src="https://www.youtube-nocookie.com/embed/<YOUTUBE_VIDEO_ID>" frameborder="0" allowfullscreen></iframe>If you're not a HackerOne employee or video content partner, please open a pull request or issue with a publicly accessible link to download the video file so it can be updloaded to HackerOne's YouTube channel. Note that video content will be need to be reviewed by various HackerOne teams; this may result in longer response times from the maintainers of this repository.