Table Of Contents

Previous topic

Publishing Program Documentation

Next topic

Right Understanding

This Page

Project Background

About the Author

I am a semi-retired programmer from the world of DOS. I am informed and opinionated on politics and religion, and I lack the social filter to care if that offends anyone. So, stop reading if you are bothered.

I believe that politics should be practiced for social good, not personal reward. Good politics requires free speech, and free speech requires a free press. Today and here, the Internet is free. This article demonstrates how to exercise your right to free (as in liberty) speech by publishing yourself for free (as in beer) on the Internet.

Why Web Publishing?

That could be my story, but there are plenty of other reasons to want to publish yourself. As this guide demonstrates, publishing on the Internet is easy enough that any idiot can do it.

Methods of Web Publishing

Several approaches to web publishing are available. The most common ways, and I have tried every one of them, might be:

  • Hand-coded HTML pages
  • Articles served on a wiki such as MediaWiki
  • Content Management Systems: Drupal, joomla!, WordPress

Each of these publishing systems requires some element of system management: having the right programming language version, upgrading the CMS, conflicts with SQL upgrades, and so forth. Content management varies by system and version, so document content becomes platform dependent. This brings us to ...

Four Documentation Truths

Truth 1: Suffering.

Publishing documentation content is suffering. For the author, website creation is suffering, domain management is suffering, hosting is suffering, server management is suffering, programming is suffering.

Truth 2: Attachment.

Document presentation requires managing the mechanics of presentation. All document management systems are imperfect and impermanent manifestations of an authoring system ideal. The author desires to create content, and as authoring moves from writing content to managing systems, frustration with system imperfections produces suffering. But the root cause of this suffering is attachment to specific mechanisms of presentation.

Truth 3: Eliminate Desire.

Eliminate the desire to control process, break the chain of attachment to document management systems, and publication suffering will end. Stop using publishing systems which require management; put the focus on content creation instead.

Truth 4: The Eight-Part Path.

  1. Right Understanding: Web Publishing Methods.
  2. Right Installation: Obtaining the Right Software.
  3. Right Configuration: Preparing Projects and git.
  4. Right Hosting: Setup a GitHub Hosting Account.
  5. Right Structure: Restructured Text Markup.
  6. Right Operation: Work Like a Developer.
  7. Right Content: Using Sphinx on Large Projects.
  8. Right Presentation: Futzing with Pretty.