The page about the wiki itself!
A complex system that works is invariably found to have evolved from a simple system that worked. The inverse proposition also appears to be true: A complex system designed from scratch never works and cannot be made to work. You have to start over, beginning with a working simple system.
- John Gall
- Explore the minimum feature set wiki
- Create software in and around ZineOS
- Discover through use the strengths and weaknesses of building software in the ZineOS
How it works
builder.coffee script is run that reads in
.md files and writes out
There is a very simple template for all the pages.
There is a CSS file that is included on all pages.
ComingSoon:tm: A .js file that is included on all pages.
The output is static html, css, and js. No webserver, no database, they live in S3 or any other static hosting environment.
pages/ index.md wiki.md ... source/ script.coffee style.styl template.html builder.coffee favicon.png index.html (compiled) main.css (compiled) wiki.html (compiled)
All the pages live in
pages/. The Markdown files are converted into
files that live at the top level. The html generated from the markdown files is
inserted into the html template. The title for the page is the first line of the
main.js is compiled from
source/script.coffee. Let's try and just use one
file for simplicity's sake. 500 lines tops. We may load some other files later
for fancier interactive pages, but the core should be quite small.
main.css is compiled from
source/style.styl. We're not savages.
favicon.png is a png that can be edited from the default pixel editor that ships with
- Keep it simple
- Wiki every day
- Only add features after they are sorely needed
Keep it simple
Example: we want to have an html template that includes the basic page header, footer, layout, shared resources.
Possible solution: find a templating library that is simple enough and featureful enough to meet our needs. Consider how large it is, how well it will integrate into ZineOS, how easy it is to call from JS.
Selected solution: write a two line function that does a good enough job for today and possibly for a long time. It has significant constraints, but is surprisingly robust. It took only 15 minutes to implement and is easy to understand where it succeeds and fails. When we outgrow it, it should be easy to replace.
simpleTemplate = (template, data) -> template.replace /\$[a-z]+/g, (match) -> data[match.substr(1)] or ""
Example: we want to render markdown into html.
Selected solution: Just use marked :P. Markdown is a nightmare. If we want to extend it we can add a pre or post processing step. The extensions will be kept to a minimum. Anyway, how can we judge before we know what they are?
Wiki every day
The only way to discover what is important is through consistent usage. Write a new page every day. Build the wiki every day. If something is harder than it needs to be it will show itself through usage. There will be simple ideas that appear through usage. It is much harder to imagine what is needed than to live and feel what is needed. The human mind will go to any length to avoid facing reality.
Only add features after they are sorely needed
Do we need a navigation bar? A list of recent articles? Not before we've written at least three or four articles.