Discourse as a blog / knowledge base since Nov 2015. Documentation is not boring

Tags: #<Tag:0x00007f8a1e4a6dc0> #<Tag:0x00007f8a1e4a6af0> #<Tag:0x00007f8a1e4a6410>

Discourse as a blog - since Nov 2015

This personal self-hosted blog & knowledge-base is doing well since 2015. 6 years of unsolicited advice on the internet – yaaaay.

This site is based on Discourse. – Originally a forum software, but the technology standard it defines is much higher than any “blog software” I ever found.

Lessons on documentation

When is comes to technical writing and hosting technical documentation Discourse is king. The system I pieced together does a fine job.
That’s not surprising since the ideas are based on Stack Overflow[1].

In contrast: have you ever searched Confluence or any other “Enterprise Wiki”? Try my site instead. You’ll be surprised what’s possible.

Features:

  • Readability (web typography) matters
    • features like syntax highlighting etc. are important for technical writing
  • Searchable (fast Full text search with preferences) content remains visible
  • Indexable (refer to the Wiki index incl. tags) content generates a catalog, which can be used to narrow down the search
  • Semantic organization (content grouped by similarity at the bottom of a post)
  • Responsiveness and page speed (the site performance and responsiveness is optimized)
  • Self-contained (the majority of the content can be archived since no 3rd parties are involved. Self-hosted draw.io illustrations etc. can become screenshots)

Missing:

  • signed content (looking into integrity checks when passing web content over multiple hops)
  • cleanup (some posts need to be deleted)

Recent changes in 2021

  • added topic map (see screenshot above) at the bottom of the blog and wiki posts to ensure readers can better understand the level of actuality. Six years is a long time in InfoSec knowledge management.
    • the reply is the hidden action of closing the posts.
  • applied a discourse-docs[2] update to fix the knowledge base entries (tag search)
  • changed the weight of the site search to prefer Wiki content
  • switched from Sendgrid to Mailjet (free), since Sendgrid silently dropped the account (readers don’t get mails, but some admin monitoring relies on it)
  • disabled Cloudflare features (minimizers) since the Discourse deployment already applies these. Trying to get rid of further scripts, that are blocked anyways.
  • CSS changes for functional elements to improve visibility when the left sidebar is active. It shows the site’s main focus topics
  • Fixed CSS for an automatic table of contents column on the right, that is shown for some longer posts
  • updates to the Linux + Docker, and the OpenBSD Nginx reverse-proxy
  • updates to the pfSense gateway
  • updates to DNS setup (DNSSEC etc.)

At this point in time, the only source of content is the domain because-security.com, or a sub-domain. I don’t include 3rd party tools unless they are self-hosted.

Next steps

I am not going for videos, since they cannot be searched well enough at this point in time. Hosting videos also is difficult and the key idea is to keep this documentation independent from any 3rd parties. I don’t have the time to host complex systems and to make good videos. Making good InfoSec videos is a lot of work.

In 2020 I was too busy to write good content. 2021’s wiki posts are going to be longer. I am going to publish some Wiki entries in a wiki-drafts category. These articles do not reflect the topics comprehensively. I will find a way to make readers aware of that because no one needs more half-baked truth in InfoSec.

While the InfoSec community doesn’t seem to have much of an interest in Serverless, Machine Learning, or Compliance for Agile / DevOps orgs yet, I do. I am certain that the level of modern expertise that will be required is going to increase going forwards. Information Security is a process, and not a status quo based on a certain technology.

No comments? Please don't register here.

On a related note, comments are disabled here because I have no time to moderate / check / approve them. You may reply on Twitter or via Email.


  1. https://stackoverflow.com/ ↩︎

  2. Discourse-docs: Documentation Management Plugin - #212 - plugin - Discourse Meta ↩︎

This topic was automatically closed after 3 days. New replies are no longer allowed.