=== SUMMARY ===

Friendly HTML Bundle Specification
version: 1.0.0
home: https://makesourcenotcode.github.io/friendly_html_bundle_spec.html

=== MOTIVATIONS ===

Offline HTML bundles (especially HTML5) are a fantastic open format for
documentation and provide many good affordances for consumers that most other
formats lack whether due to fundamental limitations of their design or due to
subpar implementations of available viewer programs.

The main drawback of offline HTML bundles is that they're harder than they
should be for novices to use. Say a novice downloaded a ZIP file of HTML,
extracted it, and went into that folder. It's far from obvious which of the HTML
files to open.

Usually the file they want to open is index.html. But this is not obvious to
newbies. It's only learned out of band from having nerdy friends who explain
some of the unspoken conventions or from knowing enough basic web development to
know the role of index.html.

Not to mention people who should know better about providing an index.html file
as an entry point for readers still fail to do so hilariously often. Just for
kicks get the HTML bundle specifying the Ada programming language and have fun
figuring out which file to open first. One would hope the authors of standards
documents would know better and follow the de facto standards for HTML bundles
but sadly this seems too much to ask.

Either way there's a discoverability problem in need of solving.

=== SPECIFICATION ===

Friendly HTML Bundles are simply folders with exactly two items.

The first is a subfolder "data" which holds the actual content arranged however
the authors see fit much like in any other HTML bundle.

The second is a "open_this_first.html" file to serve as an obvious self
explanatory entry point that leaves no room for misinterpretation. It must link
to the file or files in the data folder which are good places for consumers to
start reading and maybe have a bit of other ramp up material.

In the event the bundle is in a language other than English both "data" and
"open_this_first.html" may be translated accordingly if authors believe this
benefits intended readers.

=== COPYRIGHT ===

This is a Freedom Respecting Technology, think Open Source for everyone, not
just well off people with reliable Internet access. Learn more at:
https://makesourcenotcode.github.io/freedom_respecting_technology.html

It's (admittedly small) Open Knowledge Set consists of this file which is
released to the Public Domain.