Skip to main content

Formatting, Tone, and Style

Organizational Hierarchy

We need to write something out but here's a quick breakdown for now using After Effects as an example. 

  • Shelf : Software
    • Book : Applications
      • Chapter : After Effects
        • Page : After Effects Gotchas
        • Page : After Effects Plugins
        • Page ; After Effects Expressions

Tone & Language

Professional, personal, and nerdy are all fine. Try to keep the first-person "I" out of it if you can. If you have to use "I" try to make it clear who you are. Since a lot of content in here is from Cam's CT Handbook, there's legacy language that needs to be modified. We are working on it. 

Avoid expletives if you can – knowing that sometimes the colloquial use of naughty words is actually important when used in context (like RTFM or NFG), or you swear like a sailor and that's your tone.

Formatting

When you copy and paste text into the Bookstack WYSIWYG text editor, please strip it of formatting first (easy on a Mac: open TextEdit and make it plain-text as a shim between your text worlds). Click the question mark up top in the editor to learn the formatting hotkeys. Firefox is a browser that works, but Safari has conflicting shortcuts. 

Converting documents from something else – like Google Docs or Pages or whatever – you can either strip formatting as above (or some similar technique) and reformat manually, or you can ask your friend Claude to convert your text to markdown. Or maybe where you're pulling text from is already markdown (like Git) and this'll be e-z. 

Working with Markdown

You can switch the page editor to markdown. Once you're editing the page, the top of the editor will say either "Editing Page" or "Draft saved at HH:MM". If you click those three little dots to the right, it'll pop open a contextual menu that allows you to toggle between markdown options.

 

What's the difference between "Clean" and "Stable"? Stable works fine... read more about this if you want to here. 

 

If you don't like markdown, but you want an easy method to transpose text from somewhere else, you can switch to markdown, insert your markdown formatted text and then switch back to WYSIWYG. It'll hold the formatting you set in markdown. Nice. 


image.png

image.png


image.png

Image Use

Image uploads are limited to 1MB, so if you get an upload error, that's why!

Try to use your own images (and charts, graphs, etc), but if you need to reference something from elsewhere, be sure to credit it. Don't re-use any stock unless you have a perpetual-use-it-anywhere-forever license. This website is under a CC license, so don't be surprised if your images show up elsewhere. If you need to include some watermark, please do so tastefully hehe. 

Fair use of copy-written material : The image needs to be used transformatively (e.g., for commentary, critique, humor, or education — not just illustration) ✅

  1. Use only what you need — crop, compress, and reduce resolution so that it's not competing with the original image.
  2. Add a caption/disclaimer, e.g.: “Used under fair use for commentary/educational purposes. © NBC/Universal.”
  3. Don’t overdo it — a few well-placed media references are safer than entire meme galleries.

Image Formatting

You can place images above or below text exactly the way you'd expect, but putting images next to text requires throwing the content in a table, to make it appear that it's not in a table, you remove cell padding and borders. To keep images from being immediately against text, just add margin columns as needed. This helps keep things clean across different browser experiences, too. 

For example:

image.png

   ➡️

image.png
➡️

image.png






Tags: Please Use Them

Tags are helpful in keeping the Almanac organized. Since some items are relevant in multiple places (e.g., software tools used in-tandem with hardware tools), tagging is another way to find information. 

How-To: Pages That Belong In Multiple Locations

Should a Job Directory page be located under Finding Work or Directories?!

A book can live in two places, which is good, but what we really want is for pages to live in multiple places. To do this, we are referencing content from one page to another using Bookstack's references. For example, in the Finding Work section, we are referencing the page Job Board that lives in the Directories section.

To do this, you find the permalink number ID for the page you want to reference, and then you use the page tag below (replace the number). Please put a horizontal bar and an INFO formatted paragraph explaining that's what you're doing. 

If we replace "ID" below with "137", it will permalink to the parent Job Board page. Putting that on the child will make it so that any updates at the parent level, will happen at the child level, too.  

{{@ID#}}

Back to top