Visible styleguide and res hack to make relative stylesheets work
This commit is contained in:
Danny O'Brien
parent
e2b2e1ce81
commit
376e40d41b
2 changed files with 191 additions and 0 deletions
1
doc/res
Symbolic link
1
doc/res
Symbolic link
|
|
@ -0,0 +1 @@
|
||||||
|
../web/static/res
|
||||||
190
doc/style-guide.html
Normal file
190
doc/style-guide.html
Normal file
|
|
@ -0,0 +1,190 @@
|
||||||
|
<!DOCTYPE html>
|
||||||
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8" />
|
||||||
|
<meta name="generator" content="pandoc" />
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
|
||||||
|
<title>style-guide</title>
|
||||||
|
<style>
|
||||||
|
code{white-space: pre-wrap;}
|
||||||
|
span.smallcaps{font-variant: small-caps;}
|
||||||
|
div.columns{display: flex; gap: min(4vw, 1.5em);}
|
||||||
|
div.column{flex: auto; overflow-x: auto;}
|
||||||
|
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
|
||||||
|
/* The extra [class] is a hack that increases specificity enough to
|
||||||
|
override a similar rule in reveal.js */
|
||||||
|
ul.task-list[class]{list-style: none;}
|
||||||
|
ul.task-list li input[type="checkbox"] {
|
||||||
|
font-size: inherit;
|
||||||
|
width: 0.8em;
|
||||||
|
margin: 0 0.8em 0.2em -1.6em;
|
||||||
|
vertical-align: middle;
|
||||||
|
}
|
||||||
|
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
|
||||||
|
</style>
|
||||||
|
<link rel="stylesheet" href="/res/almanack.css" />
|
||||||
|
<script src="res/sidenotes.js" defer></script>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<center><h1 class="frontispiece">Almanack</h1></center>
|
||||||
|
<h1 id="the-conceit"><<<The Conceit>>></h1>
|
||||||
|
<p>Almanack is regularly updated catalog of the modern calendar year,
|
||||||
|
serving folks who toil in the fields of tech, just as earlier Almanacs'
|
||||||
|
accompanied agriculturalists as they navigated the seasons. It contains
|
||||||
|
a miscellany of factual pieces, stories, reviews, predictions, annual
|
||||||
|
tech rituals, calendar items, puzzles, gossip, and hoary advice.</p>
|
||||||
|
<p>Like Ben Franklin's Poor Richard before it, our Almanack is also a
|
||||||
|
lightly fictionalised framing device: namely that the publication has
|
||||||
|
played this role for enthusiasts of technological progress (with mixed
|
||||||
|
results) for the last three centuries.</p>
|
||||||
|
<p>The goal of this conceit is to let us commission and publish essays,
|
||||||
|
criticism, fiction and code on the modern world – without falling into
|
||||||
|
the trap of taking ourselves , the present or the future too
|
||||||
|
seriously.</p>
|
||||||
|
<p>Almanack is compiled over the year, and commissioned works are added
|
||||||
|
to the web site regularly, with a printed anthology of last twelve
|
||||||
|
months' pieces published in December as the official Almanack for the
|
||||||
|
next year.</p>
|
||||||
|
<h1 id="rates-and-finances">Rates and Finances</h1>
|
||||||
|
<p>We earn money through Almanack sales, online subscriptions, and
|
||||||
|
non-behavioral advertising, handcrafted to fit the conceit. Our rates
|
||||||
|
for creators are currently $500 up for a single long piece (500-1000
|
||||||
|
words), $250 for artwork, $100 for smaller items.</p>
|
||||||
|
<p>We commission longer pieces in the form of serials (both non-fiction
|
||||||
|
and fiction), and pay per installment.</p>
|
||||||
|
<p>Our finances are transparent, and can <a href="./finances.org">be
|
||||||
|
viewed, live, online</a>. We budget a burn rate of $2K a month, and aim
|
||||||
|
to always have at least six months of runway assuming the above rates.
|
||||||
|
We hold a mid-year fundraiser to grow that runway and to raise money for
|
||||||
|
the hard-cover publication.</p>
|
||||||
|
<p>When we have 18 month of runway (i.e. $78,000), further revenue will
|
||||||
|
be used to increase these rates for future contributors.</p>
|
||||||
|
<p>Contributors also receive a royalty payment from the profits (ie
|
||||||
|
after costs) of the printed collection, proportional to their
|
||||||
|
contribution.</p>
|
||||||
|
<p>Payment is on week of publication. Kill fees are 33% of agreed rate.
|
||||||
|
You retain your copyright. We and many of our contributors prefer a
|
||||||
|
CC-BY-SA license, but we can negotiate a narrower right (for a lower
|
||||||
|
rate, weirdly).</p>
|
||||||
|
<h1 id="house-style">House Style</h1>
|
||||||
|
<p>Modern online writing can be disabling and dispiriting. To stand out,
|
||||||
|
we want our readers to be more energized <strong>after</strong> reading
|
||||||
|
a serving of Almanack than they were before. They should feel more
|
||||||
|
informed, more curious, more empowered, and optimistic about their
|
||||||
|
ability to change the world for the better.</p>
|
||||||
|
<h2 id="a-light-air-of-hard-won-optimism">A Light Air of Hard-Won
|
||||||
|
Optimism</h2>
|
||||||
|
<p>Everyone here has burned through snark, irony, rage, edutainment,
|
||||||
|
simple awe, and aloofness, so we're looking for something else. It's
|
||||||
|
early days, but so far, what we have is a sense of knowing foolishness:
|
||||||
|
not so much <strong>self</strong>-deprecation, but gentle deprecation on
|
||||||
|
behalf of the entire human race.</p>
|
||||||
|
<p>We are cautiously positive about the future (although it is always
|
||||||
|
unclear if this is just part of the Conceit). You don't have to be so
|
||||||
|
positive, but if you're going to be a downer, aim to make your readers
|
||||||
|
feel more complex emotions than simple despair.</p>
|
||||||
|
<p>Almanack also has a light tone, but don't feel you need to lean into
|
||||||
|
jokiness – or the Conceit. It is <strong>always</strong> fine to ignore
|
||||||
|
our setting or mood entirely for your own purposes.</p>
|
||||||
|
<h2 id="dont-new-york-times-it">Don't New York Times it</h2>
|
||||||
|
<p>Don't talk down to the reader or over-explain. Assume that the reader
|
||||||
|
is smart, and can look things up. Prefer density of information above
|
||||||
|
explanation. Link heavily.</p>
|
||||||
|
<h2 data-custom-id="use-of-footnotes"
|
||||||
|
id="avoid-side-arguments-defenses-apologies-or-overassertion-with-footnotestm.">Avoid
|
||||||
|
side-arguments, defenses, apologies, or overassertion with
|
||||||
|
footnotes(TM). <span class="tag" data-tag-name="FOOTNOTES"><span
|
||||||
|
class="smallcaps">FOOTNOTES</span></span></h2>
|
||||||
|
<p>If you're writing online these days, it's easy to get tied up in an
|
||||||
|
imaginary dialog with future commenters – either making fierce
|
||||||
|
assertions to chase away disagreement, long defenses to try and win over
|
||||||
|
stragglers, or apologies or justifications to prevent
|
||||||
|
misunderstanding.</p>
|
||||||
|
<p>Skip all that.</p>
|
||||||
|
<p>If there's something where you feel like you need to justify or evade
|
||||||
|
or confirm an attitude, palm off that obligation by citing Almanack's
|
||||||
|
300 year long archive.</p>
|
||||||
|
<p>While apparently a modern phenomenon, Almanack is heavily implied to
|
||||||
|
have been in continuous publication for the last three hundred years –
|
||||||
|
with an back catalog that covers many of the most contentious areas of
|
||||||
|
modern debate.</p>
|
||||||
|
<p>Here, you will find that the magazine has dealt (in meticulous and
|
||||||
|
entirely unavailable depth) with your most distracting side quests, as
|
||||||
|
well as those of your most cantankerous readers.</p>
|
||||||
|
<p>Sadly, this resource is often unavailable for temporary technical
|
||||||
|
reasons, but you can still refer to them, via a `footnote`.</p>
|
||||||
|
<p>Footnotes look this:</p>
|
||||||
|
<h1 id="serials">Serials</h1>
|
||||||
|
<p>We like serials, and would like to support them when we can. Some
|
||||||
|
guidance:</p>
|
||||||
|
<h2 id="we-accept-fiction-non-fiction-and-graphical-works">We accept
|
||||||
|
fiction, non-fiction, and graphical works</h2>
|
||||||
|
<p>By fictional serials, we mean webserials or multiple-part stories.
|
||||||
|
Each episode should be 500-1500 words. We anticipate these serials to be
|
||||||
|
weekly or monthly. Our arbitrary maximum is twelve installments.</p>
|
||||||
|
<p>By non-fiction we mean long-form pieces, broken down into smaller
|
||||||
|
pieces (think a true crime podcast). We're still experimenting with this
|
||||||
|
form, and anticipate daily or weekly episodes.</p>
|
||||||
|
<p>By graphical works, a short comic series. Under 8 episodes,
|
||||||
|
please.</p>
|
||||||
|
<p>We don't at this time accept unbounded serials (i.e. traditional
|
||||||
|
webcomics, sprawling Ra-like webserials, or columns).</p>
|
||||||
|
<h2 id="show-your-priors">Show your priors</h2>
|
||||||
|
<p>We're unlikely to commission someone who hasn't already completed a
|
||||||
|
webserial or other long-running piece. Please include links to them when
|
||||||
|
you approach us.</p>
|
||||||
|
<h2 id="the-pitch">The pitch</h2>
|
||||||
|
<p>Include a general idea of an arc, and how many episodes you expect
|
||||||
|
the piece to take. Some flexibility is fine, but the pay rate will be
|
||||||
|
based on this number. We expect to have three episodes in hand before we
|
||||||
|
begin publication.</p>
|
||||||
|
<h2 id="cliff-hangers">Cliff-hangers!</h2>
|
||||||
|
<p>It's a lost art! Give your readers a reason to come back.</p>
|
||||||
|
<h2
|
||||||
|
id="use-footnotes-to-refer-back-to-previous-events-in-your-serial.">Use
|
||||||
|
<a href="#use-of-footnotes">footnotes</a> to refer back to previous
|
||||||
|
events in your serial.</h2>
|
||||||
|
<h1 id="code">Code</h1>
|
||||||
|
<h2 id="our-weird-stack">Our Weird Stack</h2>
|
||||||
|
<p>Online publications don't usually accept or commission code, but
|
||||||
|
we're weird.</p>
|
||||||
|
<p>We're <em>really</em> weird, though.</p>
|
||||||
|
<p>Part of the Conceit is that we are heavy advocates, for somewhat
|
||||||
|
arbitrary reasons, for a eldritch stack of tools. We see ourselves as
|
||||||
|
part of the tech community that work this stack, and seek to contribute
|
||||||
|
back to it. You don't have to use this stuff in your own work, but code
|
||||||
|
that uses it will be particularly welcomed.</p>
|
||||||
|
<p>We avoid proprietary (i.e. closed or non-free) software where
|
||||||
|
possible.</p>
|
||||||
|
<p>Our stack is:</p>
|
||||||
|
<h3 id="gnu-project-tooling">GNU Project tooling</h3>
|
||||||
|
<p>Yeah, it's ugly in lots of ways, but we're making a bet that when all
|
||||||
|
of this other stuff is buried under its own technical debts, GNU –
|
||||||
|
because of its historical persistence, semi-religious adherence, and
|
||||||
|
sheer doggone orneriness – will remain. We also see our work as an opportunity to
|
||||||
|
nudge GNU into the 22nd century, by being an enthusiastic advocate for
|
||||||
|
its continuation, and elaboration. That means we also use:</p>
|
||||||
|
<h3 id="guix">Guix</h3>
|
||||||
|
<p>Guix is the GNU-flavored version of Nix, implemented in Guile Scheme.
|
||||||
|
We use this as the basis for our operations.</p>
|
||||||
|
<h3 id="object-capabilities">Object Capabilities</h3>
|
||||||
|
<p>We are devoted advocates for capability-based security, and use
|
||||||
|
Spritely Goblins under the hood for our toys and infrastructure. We use
|
||||||
|
Ocapn to communicate.</p>
|
||||||
|
<h3 id="ipfs-ucans-and-the-extended-filecoin-cinematic-universe">IPFS,
|
||||||
|
UCANs and the Extended Filecoin Cinematic Universe</h3>
|
||||||
|
<p>We :heart: decentralization, and a bunch of us work in this
|
||||||
|
space. You can use other decentralized tools, but IPFS, LibP2P, UCANs,
|
||||||
|
and Filecoin are our defaults. Talking of which:</p>
|
||||||
|
<h3 id="cryptographycurrencynomics">Crypto(graphy|currency|nomics)</h3>
|
||||||
|
<p>Whaaat, that blockchain nonsense? HOW DARE YOU SIR, HOW DARE YOU.
|
||||||
|
More seriously, in a continuing vein of holding a candle for
|
||||||
|
technologies we believe cannot die (no matter how much they may deserve
|
||||||
|
to), we hold a place for crypto, both for financing/securing Almanack,
|
||||||
|
and for the stream of innovative new work, including zero-knowledge and
|
||||||
|
so on.</p>
|
||||||
|
<h3 id="django-and-python">Django and python</h3>
|
||||||
|
<p>Of course, sometimes you just have to get some actual work done. For
|
||||||
|
that, we use Django.</p>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
Loading…
Reference in a new issue