almnck/doc/style-guide.org

* <<<The Conceit>>>
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.

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.

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.

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.

* Rates and Finances
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.

We commission longer pieces in the form of serials (both non-fiction and
fiction), and pay per installment.

Our finances are transparent, and can [[./finances.org][be viewed, live, online]]. 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.

When we have 18 month of runway (i.e. $78,000), further revenue will be used to
increase these rates for future contributors.

Contributors also receive a royalty payment from the profits (ie after costs) of
the printed collection, proportional to their contribution.

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).

* House Style
Modern online writing can be disabling and dispiriting. To stand out, we want
our readers to be more energized *after* 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.

** A Light Air of Hard-Won Optimism
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 *self*-deprecation,
but gentle deprecation on behalf of the entire human race.

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.

Almanack also has a light tone, but don't feel you need to lean into jokiness --
or the Conceit. It is *always* fine to ignore our setting or mood entirely for
your own purposes.

** Don't New York Times it
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.

** Avoid side-arguments, defenses, apologies, or overassertion with footnotes(TM). :FOOTNOTES:
:PROPERTIES:
:CUSTOM-ID: use-of-footnotes
:END:

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.

Skip all that.

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.

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.

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.

Sadly, this resource is often unavailable for temporary technical reasons, but
you can still refer to them, via a `footnote`.

Footnotes look this:

[1] - See, "So, Capitalism: Good, Bad, Indifferent, or Just More Lombardy
Flimflam?", Giovanni Battista Fuggero, Almnck. 1389.

[2] - See, "Astrology -- Proof At Last", John Dee, Almnck. 1575; "A Small
Correction Regarding The Heavens", Francis Bacon, Almnck. 1605; and "No, As You
Were", George Warton, Almnck. 1675.

These references are how we keep out-of-bounds the endless distracting debates,
cliched distractions, and culture war hot-spots.  We keep a record of these [[file:footnotes.org][fake
footnotes]] -- feel free to re-use them. Very occasionally, we may even
back-fill them in and turn them into real pieces.

Almanack editors may trim apologetics or strong assertions from your piece and
replace them with these footnotes, but feel free to play with them yourself, or
add to the list.

Footnotes are only used for Almanack self-citations, and
related high-uncertainty clarifications. Use normal in-line
links for references to other online resources.

* Serials
We like serials, and would like to support them when we can. Some guidance:

** We accept fiction, non-fiction, and graphical works
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.

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.

By graphical works, a short comic series. Under 8 episodes, please.

We don't at this time accept unbounded serials (i.e. traditional webcomics,
   sprawling Ra-like webserials, or columns).

** Show your priors
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.

** The pitch
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.

** Cliff-hangers!
It's a lost art! Give your readers a reason to come back.

** Use [[#use-of-footnotes][footnotes]] to refer back to previous events in your serial.

* Code
** Our Weird Stack
Online publications don't usually accept or commission code, but we're weird.

We're /really/ weird, though.

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.

We avoid proprietary (i.e. closed or non-free) software where possible.

Our stack is:

*** GNU Project tooling
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 momentum --
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:

*** Guix
Guix is the GNU-flavored version of Nix, implemented in Guile Scheme. We use this as the basis for our operations.

*** Object Capabilities
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.

*** IPFS, UCANs  and the Extended Filecoin Cinematic Universe
We :heart: decentralization, and a bunch of the founders work in this space. You can use other decentralized tools, but IPFS, LibP2P, Spritely Goblins, and Filecoin are our defaults. Talking of which:

*** Crypto(graphy|currency|nomics)
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.

*** Django and python
Of course, sometimes you just have to get some actual work done. For that, we use Django.