cockroachdb.org redesign

[andybons]

Placeholder bug to clean up/redesign cockroachdb.org for the beta release. Ideas for what we would want on the page should be discussed within this issue.

[Linicks]

All, I would like to take this issue on, and have some ideas that will hopefully move it forward. CockroachDB, like most projects, need a great place for users to interact with it. In my mind, the project site should to be attractive, but more importantly, focused on documentation and teaching. Making the technology as approachable as possible by a diverse group of users will make it easier for individuals and organizations to get involved. In my mind, the more the merrier, as has been demonstrated by MongoDB, and others. There are many, many, was to implement this, but three seem to be appropriate at this stage of the project. One of the key tenants here is the time to implement it, and maintenance moving forward as the project grows. The solutions are listed from my highest rated suggestions to least:

• Option 1, Readme.io (http://readme.io/):

Readme.io is tool that really seems to fit OpenSource project sites, and makes it easy to create versioned documentation. What I mean by versions, is that you can easily tag the docs to match the version of the software. This is great feature, that really helps users running different releases. It’s a paid service, but is free for open source projects, all you have to do is send them an e-mail. This is ranked as option 1, because it’s the simplest to use and implement, yet powerful enough to get the job done.

Examples Sites: Mozilla brick: http://brick.mozilla.io/ Phoenix Framework: http://www.phoenixframework.org/

Option 2, Wordpress (https://wordpress.com/):

Wordpress has improved dramatically over the years, and just keeps getting better. Setting up a site is easy, and there are many hosting options. Generating and maintaining content is a snap, and there is even a great mobile app. I have used it with great success, despite my dislike of its core technologies. It’s hard to go wrong with, but with power, comes a little more complexity moving it down to option 2.

Example Sites: There are too many fantastic examples to list here, just look around.

Option 3, Hugo (http://gohugo.io/):

Hugo is an excellent alternative to Jekyll that’s actively developed. It’s written in Go, and can be use with GitHub Pages as well. The biggest advantage is that It’s written in Go, and would be a great fit for a project written in Go. Of these options, it’s the most technical, and because of that it may prevent others from contributing as readily. Many people that would be happy to contribute documentation, don’t necessarily want to setup a site generator, etc. Easy and simple always seem to win out in this department. Because of the added complexity I moved it down to option 3.

And finally the big question. Of these three options, do any of them seem like the right path to take? I would like to start work on this soon so that when the beta is ready the site is ready as well, possibly even before. Of course many other details need to be sorted out, this is just an initial attempt to get this going.

Thanks! -- Nick Pavlica

[petermattis]

Would love to have your help here Nick. Be aware that there is some work in progress to flesh out the basic design for the website.

I did some brief investigation into documentation tools a few weeks ago and ran across http://mkdocs.org which is what Docker uses. The documentation is markdown which is converted to a static site and can then be hosted on AWS or elsewhere. Seemed simple and straightforward.

My guess is that the website will use a combination of technologies. Something like mkdocs.org (or perhaps readme.io, haven't really looked at it yet) are good for the documentation portion. But we'd also like to have a blog which seems more aligned with Wordpress or Jekyll or Hugo.

[bdarnell]

Readme.io appears to have blogs as well (http://brick.mozilla.io/v2.0/blog). I haven't explored it in depth but it looks nice at first glance.

One more possibility is http://sphinx-doc.org/, which I know well. It has a python bias but can be used with other languages. It's best suited to reference documentation and has good cross-referencing support. Both Sphinx and mkdocs can be hosted on readthedocs.org, which provides some of the versioning and github-syncing features that readme.io has.

I'd really prefer to avoid wordpress.

[Linicks]

All, I think the primary question at this point is determining the workflow of the documenters. Of the approaches mentioned thus far we can separate the approaches into two basic categories. The first includes tools like redme.io, and WordPress, that have a great through the web experience. The second category includes hugo, mkdocs, or sphinx-doc, that are more focused around a source control mechanism like git. Certainly there are pros and cons to both approaches. One of my goals is to make it as simple and easy as possible for documenters to jump in and fix a simple typo, or fill in the important missing pieces. Often the biggest problem with technical documentation is that it’s created by someone who already has all of the details in their mind. This makes it very easy for little bits of information to be left out. This a very natural thing for these authors to do because it’s an obvious detail in the author's mind. Unfortunately, the missing details can often make the documentation look like hieroglyphics to new users of the project. If one of the through the web options isn’t selected, I think we should strongly consider Hugo because it can act as a complete solution. While many use it to blog with, many others use it for their main website, documentation, and blog. The pros to this approach is that there is a common tool that can be used for all three of these needs. This helps reduce complexity because once you understand Hugo, you can contribute to all three things using skills that you already have. Additionally, some of the through the web(TTW) functionality can be mimicked as demonstrated on the Hugo website. If you go to their introduction page (http://gohugo.io/overview/introduction/), you will notice a link at the bottom of the menu on the left that says “Refine this Page” that takes you to github and starts the forking process for you (https://github.com/spf13/hugo/edit/master/docs/content/overview/introduction.md). This does allow you to make some edits and previews through their web interface before submitting the change for merge. This is a hybrid approach that may help bridge the gap. Using Hugo also promotes the use of Go, and helps promote the ecosystem around it as well. Of the two through the web solution presented thus far, readme.io is really a nice hybrid between something like wordrpress, and one of the xyz generators. The documents are markdown, and can be easily exported if needed. The workflow is simple, and is as easy to use as Google docs. It seems to have all the essentials, including a blogging utility, but I don’t know how flexible it is for specific site customizations, etc. Wordpress can pretty much do anything that you want it to, however, like Hugo it would require more heavy lifting to get it setup and working the way you want it to. When you guys have an opportunity, can you take a closer look at Hugo, and Redme.io. This may help clarify some of my thinking. It would also be great so see some of the design mockups that are in progress so that I can get a better feel of the big picture. With a name like CockroachDB, I have visions of scattering cockroaches in the header, or a flashlight the rotates back and forth through the dark highlighting all of roaches. Of course these are just some fun ideas that I thought of.

Thanks! -- Nick

[petermattis]

I lean towards the solutions in which the markdown in version control is primary. For example, CoreOS seems to have taken this approach (https://github.com/coreos/docs). Not sure what tool they are using, but I'm sure we can find out. I agree with your sentiment to give more weight to a tool that is Go based, though that shouldn't be the primary factor.

We don't have any design mockups yet, but I imagine something similar to many current open source projects with an about page, blog and documentation. I don't think there is a need for any sort of advancement of the state-of-the-art here.

Spencer has a vision of some sort of Soviet-era-style artwork showing a nuclear apocalypse in the background with cockroaches scurrying around in the foreground.

[Linicks]

All, If there aren't any objections, I will start working on a Hugo and GitHub version of the site. I will probably start with a generic bootstrap or foundation template that we can build from. The nuclear Apocalypse also sounds like a fun design idea.

Thanks! -- NIck

[petermattis]

I have no objections to getting started with Hugo. Hard to make perfect decisions in areas like this ahead of time. If Hugo turns out to be problematic we can always switch.

[Linicks]

Awesome! I'll move ahead, and will share what I have as soon as it's somewhat coherent so that I can start getting feedback. I'm not sure I ever make perfect decisions, but hopefully I make some good ones once in awhile :)

--Nick

[Linicks]

All, I just wanted to give an update on my progress as of 04/04/2015. So far I have a basic site and theme started with Hugo. I've mostly been working on artwork, layout, and roughing in some of the content from the github readme. Hopefully, within a week or two I will have something that is far enough along to share.

Thanks! --Nick

[petermattis]

Glad to hear you're making progress, though I'm a little worried there is a bit of duplication of effort here with work we have ongoing (e.g. the artwork and layout). Mind giving a preview of what you've got (even if it is non-functional)?

[Linicks]

Hi Peter, I spun up a temporary server so that you can see what I have started (http://104.236.21.54/). Please keep in mind that this is a work in progress, and many things aren't in place, are broken, etc. It's currently best to view it full screen, but I've started work on mobile and other smaller screen sizes. The theme that I'm creating is called apocalypse, but with Hugo other themes can be created and swapped in ad out as needed. I was under the impression that allot of work hasn't been done thus far which is why I started building a theme:

"We don't have any design mockups yet, but I imagine something similar to many current open source projects with an about page, blog and documentation. I don't think there is a need for any sort of advancement of the state-of-the-art here. "

If there is work that's done please share it so that it can be used in a theme(s). I don't want to waste my time or others by not being on the same page.

Thanks! -- Nick

[petermattis]

Ok, let's get you on the same page. We haven't talked much about it yet, but we've formed a company (Cockroach Labs) around the open source project. The company has engaged a small design firm that we've worked with in the past to help with the branding and design. The design firm is focused on the design aspect of the site (logo, colors, fonts, etc) and we'll still need help implementing the design (i.e. what you've been doing with hugo). I'm happy to share what we have so far. Email me at petermattis@gmail.com.

Btw, I like the hero image you used. What is that from? "Start an infestation"? Ha!

[Linicks]

Peter, Thanks for getting me up to speed, I appreciate it!

The background image I used for the "hero" was:

Post Apocalypse - by nirmalyabasu5
- http://www.deviantart.com/art/Post-Apocalypse-437238188

"Start an infestation" :

I thought it would add some fun and personality to the project by running with the cockroach theme.

I'm taking the temp server down for now, but will add a screenshot of the theme I started for reference. I will Email you so that we can sync up on the Cockroach Labs theme.

Thanks! -- Nick

[tamird]

cockroachdb.org redirects to http://www.cockroachlabs.com/ now. Shall we close this?