Working with Static Sites

Chapter 4. Building a Documentation Site

Brian Rinaldi

While there are many different types of documentation sites—from hardware or software documentation to project or policy documentation—most of these sites share some common characteristics.

Characteristics of a Documentation Site

The first characteristic of a documentation site is that they tend to have multiple, and often numerous, contributors. In the case of project or policy documentation, contributors might exclusively be company employees. However, in a software world increasingly dominated by open source, many documentation sites have a large number of external contributors.

Second, a typical documentation site is fairly simple and straightforward in terms of features and design. Most of the time, the layout and design is intentionally simple and geared towards readability over style. Outside of things like comments or a runnable example, a documentation site rarely includes complex, dynamic functionality.

Third, most documentation sites change infrequently. Usually, a documentation site receives periodic significant updates with occasional minor ones in between.

While none of these characteristics is a requirement for choosing a static site, they do enable documentation sites to take advantage of the benefits of using a static site generator.

All that being said, there are some drawbacks to choosing a static site generator for building a documentation site. For one, it generally requires that a developer or development ...