RE: [openeverything] Huddle work on documentation

[Sebastien Lambla]

The approach is sound:

https://github.com/openrasta/openrasta.github.com 

I'll attach the logo designs when I get back to London, the color scheme should come from that.

Of course designers are more than welcome to suggest enhancements to the existing logo, get the info flowing.

Comments:

- Links should include the CI build links for each of the packages

- credits can be taken from the ohloh.net page (http://ohloh.net/p/openrasta/)

- I think we ought to have a link bar at the top with the links to subprojects (aka openwrap and openfilesystem), same bar we could replicate on other sites.

Rest looks mighty fine with me. I'd make sure that the toc is filled-in for changes in the documentation structure, beyond that, knock yourselves out.

There is some additional content that ought to be in the documentation:

 - While codecs are what we know thigns are called, having a list of supported codecs and their specificities in both how tos and reference would be important (mostly, webforms, spark and razor). 

- For custom bindings, I think we should introduce the interceptor concepts before the binding ones, because people try to use binding for things they probably ought not to. If we don't have that, we should.

- We need content on authetnication and authorization in how to. They ought to be in the TOC too.

- Some how tos for common questions on github would be welcome, so having those mapped out would be a good way to incite people to document this.

I can allocate time to write those new pieces as needed, but adding those to the task list would make tracking progress easier.

Comments?

Seb

---

From: openevery...@googlegroups.com [openevery...@googlegroups.com] on behalf of Ian Cooper [ian.hammo...@gmail.com]
Sent: 14 June 2012 10:28
To: openevery...@googlegroups.com
Subject: [openeverything] Huddle work on documentation

Hi guys,

We spent today coming up with a plan for documenting OpenRasta. We now want to share that plan so as to get feedback. We would intend to start parcelling up the work between the four of us currently committed to this effort at Huddle next week (19 JUN), so we would be grateful if you could raise issues before then. (BTW we is myself, Pete, Matt and Mimmo here)

The Website

Approach

For the OpenRasta site we propose an organization site for OpenRasta hosted on GitHub i.e. openrasta/openrasta.github.com (similiar to openwrap/openwrap.github.com)

The idea is to use the OpenWrap pages as a thematic template for the OpenRasta page so that they have a 'family' feel

-- For that we need to agree on some logo designs and similiar collateral

-- We'll need to add a CNAME file for www.openrasta.org

-- We'll need to change the DNS for www.openrasta.org https://help.github.com/articles/setting-up-a-custom-domain-with-pages

Content

We think a simple page like NancyFX, Sinatra, Node.JS that highlights the strenghts of OpenRasta by showing how a simple GET is handled would show OpenRasta in its best lite

 (see http://www.sinatrarb.com/ or http://nancyfx.org/ or http://nodejs.org/)

How to Get

We should have an OpenWrap install line as per the OpenWrap page

And, pragmatically, we probably ought to have a NuGet command line as well (we want to drive adoption after all)

 We then want links for the following:

 -- Documentation (goes to GitHub wiki)

 -- Fork Me (goes to GitHub repo; we like the node.js top right corner design)

 -- Community (Sub page: OpenEverything-Dev mailing list, Twitter etc.)

 -- Credits/Contributors (Sub page: The who's who - can we build from commits?)

 -- OpenWrap (link to OpenWrap)

The Wiki

On the documentation wiki we would like to reorganize a little bit. We would expect some of the same pages to be linked through Tutorial, How To, Reference; the idea is to give different way to walk the doco for novice, inexperienced and experienced users

-- A brief description of what OpenRasta is

-- The simplest example of a simple handler with configuration (straight on the page not a link - may build on the one on the website)

-- A Tutorial Section

-- Including a Getting Started section

-- Basic walkkthroughs, not covered in how tos below

How Tos

-- Resource Configuration

-- IoC Configuration

-- Codecs

-- Custom Bindings

-- Pipeline

-- Contributors

Reference

-- Resources

-- Handlers

-- Codecs

-- Configuration

-- PipelineContributors

-- Object Binders

-- Dependency Injection

-- -- Available Dependencies

-- Uri Decorators

Comments?

[Ian Cooper]

Let's get the new structure up, then we can decide on new pieces that we need to commission. I expect we may do a little clean up as part of the initial phase and suggest some re-writes. One or two of the crew here seem keen to write tutorials/doco. We probably should not discourage that as its rare.

[Sebastien Lambla]

True. Glad to have you on board guys. 

--

Seb

[Ian Cooper]

For anyone tracking this. Most work today was focused on the wiki. We're splitting the work internally and the other guys who are going to look at the site were out today.

Most interesting part of that was looking at how we were going to manage changes. That turns out not to be as easy as it seems because you can't use a normal Git workflow with the wiki

It appears that this is the recommended process (fork to local repo, manual merge): http://fusiongrokker.com/post/how-you-can-contribute-to-taffy-documentation Who knew that step would prove so thorny?

So that's what we are going to use. For now whilst it is internal to Huddle we will manage the list of work. However if folks express a desire to have more visibility or help, we can break out the task list more publicly via Huboard

[Max Edwards]

I am available to help but with limited knowledge of OpenRasta documentation may not be the best thing for me to do. Perhaps I can follow tutorials from scratch to see if I run into problems?

If you need any other help just shout.

[Sebastien Lambla]

Any reason why you don't just make the changes on the master wiki? Edition is already avail to everyone, forking may complicate things slightly?

---

From: openevery...@googlegroups.com [openevery...@googlegroups.com] on behalf of Ian Cooper [ian.hammo...@gmail.com]

Sent: 19 June 2012 18:10
To: openevery...@googlegroups.com
Subject: [openeverything] Re: Huddle work on documentation

[Sebastien Lambla]

Oh, by the way, while I think of it. Please do not rename the existing pages without letting me know, there are redirects from the old trac sites that are in place to the new wiki, page name changes would break those and would require some updates to the redirects I've set up.

S

---

From: openevery...@googlegroups.com [openevery...@googlegroups.com] on behalf of Ian Cooper [ian.hammo...@gmail.com]
Sent: 19 June 2012 18:10
To: openevery...@googlegroups.com
Subject: [openeverything] Re: Huddle work on documentation

[Max Edwards]

Still available to help if anything needs doing ;)

[Sebastien Lambla]

Added some comments. Uploaded logos on the site.

Can you reissue the pull request and i'll pull it in?

Seb

---

From: openevery...@googlegroups.com [openevery...@googlegroups.com] on behalf of Ian Pender [ianmp...@googlemail.com]
Sent: 26 June 2012 14:25
To: openevery...@googlegroups.com
Subject: Re: [openeverything] Re: Huddle work on documentation

Hello Seb! Long-time no-see.

IanPender here, I've rocked up at @Huddle and I'm helping with the doco.

I've sent a PullRequest with a first-cut of the github:pages in the OpenWrap style.

We still need to:

- Get logo / css for the site
- Add the ‘OpenEverything’ bar
- Get the rest of the copy
    - I wasn’t sure how many contributors to detail (I’d like to say all… but OpenWrap has far fewer listed)

- Change the wiki

Let me know if there's any issues... it would be great if someone could pull...

On Friday, 22 June 2012 12:54:15 UTC+1, SerialSeb wrote:

Oh, by the way, while I think of it. Please do not rename the existing pages without letting me know, there are redirects from the old trac sites that are in place to the new wiki, page name changes would break those and would require some updates to the redirects I've set up.

S

---

From: openeverything-dev@googlegroups.com [openeverything-dev@googlegroups.com] on behalf of Ian Cooper [ian.hammo...@gmail.com]

Sent: 19 June 2012 18:10

To: openeverything-dev@googlegroups.com

Subject: [openeverything] Re: Huddle work on documentation

[Ian Pender]

Will do. Just patching my fork with your comments. I'll add the credits with the contributors from  http://ohloh.net/p/openrasta/ . Should take 10 mins

On Tuesday, 26 June 2012 15:46:48 UTC+1, SerialSeb wrote:

Added some comments. Uploaded logos on the site.

Can you reissue the pull request and i'll pull it in?

Seb

---

From: openeverything-dev@googlegroups.com [openeverything-dev@googlegroups.com] on behalf of Ian Pender [ianmp...@googlemail.com]

Sent: 26 June 2012 14:25

To: openeverything-dev@googlegroups.com

Subject: Re: [openeverything] Re: Huddle work on documentation

[Sebastien Lambla]

This has been integrated. Thanks :)

Seb

---

From: openevery...@googlegroups.com [openevery...@googlegroups.com] on behalf of Ian Pender [ianmp...@googlemail.com]
Sent: 26 June 2012 16:32
To: openevery...@googlegroups.com

[Ian Pender]

One more push... I've updated the copy to be less like the wikipedia copy. You can see the changes in my last push.

Let me know if there's more general changes / logo integration needed,

On Tuesday, 26 June 2012 18:40:53 UTC+1, SerialSeb wrote:

This has been integrated. Thanks :)

Seb

---

From: openeverything-dev@googlegroups.com [openeverything-dev@googlegroups.com] on behalf of Ian Pender [ianmp...@googlemail.com]

Sent: 26 June 2012 16:32

[Sebastien Lambla]

Think we should try and update the site's design a bit. OR should probably adopt the green of the logo. Will try to give it a shot tonight. 

Did you see the logos? They're in the download section of the site. 

--

Seb