Contributing: Writing Content
The website has three content sections:
- Hack guides describe the Hack language
- HHVM guides describe how to install, configure and run the HHVM runtime
- The API reference is generated from the API definitions, and this site includes examples for each API
File Naming Conventions
A guide is a folder with a numeric prefix:
$ ls guides/hack/
01-getting-started/
02-source-code-fundamentals/
...
These numbers are used to control the ordering of guides on the website, and are not shown in the UI. They do not need to be sequential: there can be gaps.
Within each folder, there are markdown files (written in GitHub
flavored markdown), a foo-category.txt (used
for grouping on the home page) and a foo-summary.txt (shown as a subheading on
the home page).
$ ls guides/hack/01-getting-started/
01-getting-started.md
02-tools.md
getting-started-category.txt
getting-started-summary.txt
Pages use the same numbering system to control their order within a guide.
Writing Conventions
Guides are written in a relatively informal tone, addressing the reader as "you". Assume the reader has some programming knowledge but no familiarity with Hack.
Each page should have a clear purpose, starting with a short description of the concept it's describing. Examples should always be provided, preferably under 15 lines.
We assume the reader has a relatively recent version of HHVM. References to very old features will be removed, but we provide Docker images of historical site versions if needed.
It's not necessary to document all the incorrect ways a feature can be used. Content should focus on correct usage, and users can rely on the Hack type checker to tell them when they've done something wrong.
Links
Internal links should be absolute paths without a domain,
e.g. /hack/contributing/introduction.
Image paths should be relative to public,
e.g. /images/imagename.png.
When removing or renaming pages, set up a redirect from the old
URL. See Guides::getGuidePageRedirects.
Styling
We use Sass to style the website, and the source files are in sass/.
The CSS files are generated by the build script.