Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history 
- Correct linguistic flaws and fix links (thanks @sottwell)
- Add link to live demo
  • Loading branch information
@hugopeek
hugopeek committed Feb 22, 2017
1 parent 1fd9524 commit 8e95ab5
Showing 1 changed file with 32 additions and 14 deletions.
46 changes: 32 additions & 14 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Romanesco is an **experimental** collection of tools for prototyping and building websites. It integrates a front-end pattern library directly into a CMS. It aims to combine various best practices like code reusability, iterative development, a content-first approach and modular, responsive content editing into 1 coherent ecosystem.

Romanesco spans across of 3 main areas:
Romanesco spans 3 main areas:

- **Romanesco Soil** (this repository)
A pre-configured base installation, to quickly get you started with each project.
Expand All @@ -11,7 +11,7 @@ A pattern library to manage all reusable elements from a central repository.
- **Romanesco Backyard**
A project hub, to display (and experiment with) the pattern library on a separate subdomain.

The elements in the pattern library are structured according to the atomic design principles, as first outlined by Brad Frost. He does a better job at explaining how those principles work than I ever could, so if you're not familiar with it yet, I suggest you [read up on that first](http://patternlab.io).
The elements in the pattern library are structured according to the atomic design principles, as first outlined by Brad Frost. He does a better job at explaining how those principles work than I ever could, so if you're not familiar with it yet, I suggest you [read up on that first][7].

Romanesco differs from the original PatternLab however in 2 distinct ways:

Expand All @@ -25,17 +25,15 @@ This means that when you are done installing Romanesco, the only thing you reall

So *publishing* your project will require you to purchase a license, but getting started with Romanesco is still free. If you're OK with that notion, then let's move on!

## Whom is it for?
## Online demo

Indivual webdesigners, front-end developers, content editors, UX specialists, bloggers, marketeers, computer savvy business owners... But also digital agencies, companies, educational institutes, government bodies, NGOs or other types of organizations...
Want to see Romanesco in action first? I've set up a demo install on:

Anyone wanting to build their own website, or develops them for a living.
http://romanesco.fractalfarming.modxcloud.com/

Yes, that is a *very* broad definition. But Romanesco is not a framework or pattern library alone, nor just a pre-configured CMS. It is an ecosystem; a way of building sites. One that differs from many of the currently practiced workflows. And thanks to the power of pattern libraries and ContentBlocks: one that scales remarkably well. You can use it with the defaults and quickly be on your way with publishing content, or you can turn it into a Git powered R&D lab and production facility, reusing patterns, fixing issues and developing new features for *all* your projects simultaneously as you go along.
The interesting part (with the front-end pattern library and live examples) is located at:

## Disclaimer and warranty

Yes, those are big promises. And I'm in no way claiming that Romanesco is an answer to all your problems and global inequality. Again: it's an **experiment**. I've been working on it for over a year now and it feels like I'm only just scratching the surface. But does that mean Romanesco is not production ready yet? No. I'm using it in projects already and for the most part, it is stable. But you can't throw any design or UX problem at it just yet, and sometimes moving forward also means breaking things. I will try however, to draw some edges around the "safe zone" the best I can. There's an indicator in the front-end library for example, which informs you if a pattern is safe to use or not. I will also be working on adding more usage instructions and general guidelines over the next few months.
http://hub.romanesco.fractalfarming.modxcloud.com/

## Installation

Expand All @@ -56,7 +54,7 @@ What you'll need to get started:

- An operational web server (minimum PHP version: 5.4)
- The latest [MODX distribution][4]
- The Romanesco Starter Kit zip file
- The Romanesco Starter Kit zip file *(coming soon, sorry!!)*
- Access to your database (to run an SQL query)
- A ModMore account and API key
- Patience and an open mind
Expand All @@ -67,13 +65,13 @@ Don't be scared of:
- Complicated build scripts, NPM modules or configuration files. Because there aren't any.
- Lack of technical skills. This will be a point and click adventure!

[Check the wiki for detailed instructions](https://github.com/hugopeek/romanesco-soil/wiki/Basic-installation)
[Check the wiki for detailed instructions][5]

### Advanced installation

But Romanesco can be more than that. Much more. That's where the advanced installation comes in. This installation uses Gitify to set things up and Git to keep track of changes. Gitify is a tool that turns your database-based MODX installation into a file-based ehh.. Bunch of files. The biggest advantage of that, is that it allows you to commit those files into a version control system (or VCS). By far the most widely used VCS in the world today is Git, and with good reason. Git does a very good job in maintaining an efficient and reliable version history of your project, without getting in your way too much by forcing you into a certain workflow. It also makes working on the same project with other people a lot easier, mainly because it can detect conflicting changes and help you merge them properly into a stable piece of software.

For a more in-depth explanation on the benefits of using Git and Gitify, and of how they work, check out the [Wielding Gitify](../Deployment/Wielding_Gitify.md) and [Git workflow](../Deployment/Git_workflow.md) sections.
For a more in-depth explanation on the benefits of using Git and Gitify, and of how they work, check out the [Wielding Gitify](../Deployment/Wielding_Gitify.md) and [Git workflow](../Deployment/Git_workflow.md) sections. *(Working on these docs still..)*

Working with Git also opens up the possibility to keep your installation up-to-date with the latest Romanesco release.

Expand All @@ -98,8 +96,28 @@ Working with Git also opens up the possibility to keep your installation up-to-d
- Git. As long as you know what a repository is and how to clone one, you'll be ok. You will learn the rest as you go along.
- Gitify. It is not as scary as you think. I will try my best to ease you into it and show you why it's absolutely worth investing your time and effort into learning how to operate this tool.

[Check the wiki for detailed instructions](https://github.com/hugopeek/romanesco-soil/wiki)
[Check the wiki for detailed instructions][6]

## Whom is it for?

Indivual webdesigners, front-end developers, content editors, UX specialists, bloggers, marketeers, computer savvy business owners... But also digital agencies, companies, educational institutes, government bodies, NGOs or other types of organizations...

Anyone wanting to build their own website, or develops them for a living.

Yes, that is a *very* broad definition. But Romanesco is not a framework or pattern library alone, nor just a pre-configured CMS. It is an ecosystem; a way of building sites. One that differs from many of the currently practiced workflows. And thanks to the power of pattern libraries and ContentBlocks: one that scales remarkably well. You can use it with the defaults and quickly be on your way with publishing content, or you can turn it into a Git powered R&D lab and production facility, reusing patterns, fixing issues and developing new features for *all* your projects simultaneously as you go along.

## Disclaimer and warranty

Some of the statements above are big promises. And I'm in no way claiming that Romanesco is an answer to all your problems and global inequality. Again: it's an **experiment**. I've been working on it for over a year now and it feels like I'm only just scratching the surface. But does that mean Romanesco is not production ready yet? No. I'm using it in projects already and for the most part, it is stable. But you can't throw any design or UX problem at it just yet, and sometimes moving forward also means breaking things. I will try however, to draw some edges around the "safe zone" the best I can. There's an indicator in the front-end library for example, which informs you if a pattern is safe to use or not. I will also be working on adding more usage instructions and general guidelines over the next few months.

## Yeah, but.. What is *a* Romanesco?

In nature, the romanesco is a curious crossover between a broccoli and a cauliflower. It's flowers are shaped by repeating mathematical patterns, forming a mesmerizing collection of green fractals, spiraling up and multiplying in perfect resonance with Fibonacci's golden ratio. The result is a vegetable that looks almost too stunning to be eaten!
In nature, the romanesco is a curious crossover between a broccoli and a cauliflower. Its flowers are shaped by repeating mathematical patterns, forming a mesmerizing collection of green fractals, spiraling up and multiplying in perfect resonance with Fibonacci's golden ratio. The result is a vegetable that looks almost too stunning to be eaten!

[1]: https://modx.com/get-modx/
[2]: http://semantic-ui.com/
[3]: https://www.modmore.com/contentblocks/
[4]: https://modx.com/download/latest
[5]: https://github.com/hugopeek/romanesco-soil/wiki/Basic-installation
[6]: https://github.com/hugopeek/romanesco-soil/wiki/
[7]: http://patternlab.io

0 comments on commit 8e95ab5

Please sign in to comment.