New DataMapper website

[solnic]

Hey Everyone,

We've been talking about a new website for the project for a long time and I guess it's time for some action. We want to start putting together content about the upcoming DataMapper 2 and at the same time leave DM1 content (it's good-enough as it is). I just want to start a discussion here about how you imagine the new site, how we should organize it, what sections we should have and most importantly - what color scheme we should use :)

From my point of view I'd imagine having 2 separate sections for DM1 and DM2. The first one would include what we already have but for DM2 I think we should prepare a better structure with better navigation so it's easy to find user docs, api reference, installation notes etc. One of the things I'd like to introduce is to use code examples that are actually tested (so we could have a project with all the code snippets that are on the website and we just run the tests on travis to make sure our user docs don't have out-dated or broken examples).

We'd *love* to get some help from people.

Please let me know if you're interested :)

Cheers!

# solnic

[solnic]

On Tuesday, November 27, 2012 1:50:32 PM UTC+1, Mihael Konjević wrote:

Hello everyone,

I'd definitely like to contribute to the new DataMapper site. First I think we need to define how should we approach new site. I was working on sites for these open source projects:

http://javascriptmvc.com/

I like this one! Here's a list of other sites that people pointed me to today that I find really lovely:

http://emberjs.com/ - personal favorite

http://batmanjs.org/

http://compass-style.org/ - despite the dark theme, it's still really nice and easy to read/navigate

 

So, JavaScriptMVC site is IMHO closest in the form of what we should do for the  DataMapper site. Other two sites, have the form of one-long-page-documentation, and while I think a page like that would be useful for the DataMapper, we should probably do something more "classic" in terms of design and organisation.

Yes I agree. We're gonna have a lot of content so a single page is not an option.

 

I think that first we should define is a site map, and how we want the docs and examples to look. After that we can work on mockups and finally on the design.

Right. So here's what I've got in mind:

1. Home page with a "getting started" info - I like when I open some project website and w/o any digging I can learn quickly how to get started with it. So that'd be nice to have for DM too.
   
2. Main sections in the menu would be:
   
1. Documentation
2. Tutorials (or Guides?)
3. API Docs
4. Community
1. Blog with latest news
2. Info about contributing
3. Links to related resources (google group, irc channel etc)

Now the trick is that we need to split Documentation in sub-sections based on the individual projects that we're going to have in the DM2 stack. For example "Mapper", "Session", "Engines" etc. But I guess a simple nav menu on the left side will be enough. For API docs we can simply embed our YARD docs from rubydoc.info.

In community section it would be nice to have a larger "Contribute" section. We could add some resources about development process etc. This could potentially have a lot of content :)

OK so these are my initial ideas. Oh and personally I prefer a light theme for the site and code examples!

Thanks!

# solnic

[manu]

+1 for the lovely jsmvc

code examples are my lifeblood, it's the only way I manage to figure out how things work. Having a way for the community to add examples under each section would be nice, but clearly separated from the 'official' examples.

better integration of the API docs would also be a bonus. 

[solnic]

Yeah I like the concept of having comment section for every doc/tutorial page where people can provide their own code examples.

[solnic]

On Wednesday, November 28, 2012 8:55:52 AM UTC+1, Alex P wrote:

Hey guys. 

Not sure if it's a good idea, but worked just fine for us. We've created Docslate (https://github.com/clojurewerkz/docslate), which is pretty much a basis for all the guides/websites for our projects.

I understand that long-term plan may be going anywhere far, but for starters simple Twitter bootstrap and Jekyll website should be just fine, or?.. 

Totally. I want to keep using github pages as long as it is sufficient for us.

 

Check it out. In the end, it's quite customizable, has good typography. The latest effort I'm aware of that's using pretty much same thing is: Clojure Documentation Guides http://clojure-doc.org/articles/language/interop.html , there's a more "customized" project, Monger: http://clojuremongodb.info

But once again - it's just a matter of time, every project sooner or later gets lots of style customizations as content grows. I really suggest taking a look at either docslate itself, or creating same thing (Bootstrap + Jekyll (or any lightweight blogging engine you love) + Markdown (or any markup language you love)), that will get you started real quick (for instance, http://typhoeus.github.com was created in under 30 minutes), and will stimulate project growth, which is in the end more important than pretty looks

Thanks I'll check them out :)

# solnic