The Orchard Book

Topics: Announcements
Sep 9, 2011 at 5:59 PM

I talked about that briefly on Twitter and a few key people liked the idea, but I don't want to ruffle any feathers. So if you are currently actively writing a book on Orchard, let me know, publicly or privately.

So here is the idea: writing a book takes a lot of time and effort, and not everyone is OK taking that huge task on their own. I know I'm not. So I was thinking that we could divide and conquer here, and collaborate on something in smaller chunks.

I just created a public Google doc here: Anyone can view, and I'll give editing rights to anyone who commits to writing at least one chapter. The book will be under a Creative Commons license. I will act as editor. When the work is done, we would have a print edition, the royalties for which would be split among the authors proportionately to their contribution in words.

For starters, let's gather volunteers and chapter ideas, and build a reasonable TOC.

What are your thoughts?

Sep 9, 2011 at 6:04 PM

I like it

Sep 9, 2011 at 6:44 PM
Count me in.

On 9 Sep 2011, at 18:59, "bertrandleroy" <> wrote:

From: bertrandleroy

I talked about that briefly on Twitter and a few key people liked the idea, but I don't want to ruffle any feathers. So if you are currently actively writing a book on Orchard, let me know, publicly or privately.

So here is the idea: writing a book takes a lot of time and effort, and not everyone is OK taking that huge task on their own. I know I'm not. So I was thinking that we could divide and conquer here, and collaborate on something in smaller chunks.

I just created a public Google doc here: Anyone can view, and I'll give editing rights to anyone who commits to writing at least one chapter. The book will be under a Creative Commons license. I will act as editor. When the work is done, we would have a print edition, the royalties for which would be split among the authors proportionately to their contribution in words.

For starters, let's gather volunteers and chapter ideas, and build a reasonable TOC.

What are your thoughts?

Sep 9, 2011 at 7:24 PM

What an excellent idea! I would really love to read an into-depth book on Orchard with the complete API, advice, best practices, extensibility scenarios, etc.
I can't commit anything right now, but in the upcoming months I will see if I can write something down that I learned from my experience on writing custom themes for Orchard and hurdles I came across.

When I know for sure I can dedicate myself into writing at least a chapter, I'll get back and then we'll see if it's useful, as my knowledge doesn't go as far as most of the contributors to this project. But it does give me a change to investigate many things that I need to know, since I put Orchard to good use to real customers needs.
In any case I will support this project as much as possible and try to review texts and provide feedback, all in the spirit that every little bit may help.


Sep 9, 2011 at 7:54 PM

If you want to participate, please specify your Google Docs id so that I can add edit rights for you.

Sep 9, 2011 at 7:58 PM
Edited Sep 9, 2011 at 7:58 PM

digital11 at

Sep 9, 2011 at 8:20 PM

I started a rough list of section & chapter ideas. Will add more as I think of them.

Sep 9, 2011 at 8:58 PM

I assume my Gmail Id will work as a Google Docs id: skywalker at thedutchpirates dot com

Sep 9, 2011 at 10:01 PM

This is a really interesting idea. I've not authored a book, or even part of a book, before so I don't know how much of a commitment that is. I'd like to say "count me in" too, but will think about it some more before committing.

Sep 9, 2011 at 10:32 PM

I might not be a good writer but I would offer to proof-read parts or the whole. This is a big pain point for me in many books - typos, grammar and punctuation. So while I might not be able to contribute much content, I'd offer to help with at least this much.

oliver.friedrich (at) gmail [.] com

Sep 10, 2011 at 4:55 AM

Notes cut and pasted from the document:

I think it may be a good idea to illustrate the above topics by creating a sample website. Each chapter can build from installation to deployment. This could take the form of Contoso or something a little more fun. - ST

The book must be fundamentally different from the documentation. It must have a narrative ark. Chris’s idea of following the building of a site from beginning to end is in line with this. It also enables us to move smoothly from setup, creation of some simple static contents, adding a few modules from the gallery, and then building one’s own theme and modules - Bertrand

Sebastien: My point on this is that there could be two main sections, or maybe two books. One on a website developer’s perspective, the other one on the API, covering all the architecture. You could also argue that any part could be explained by developing specific modules, or functionalities. This is not a really good medium for discussions …

Good point, Sébastien, we can move that to the discussions forum...

Sep 10, 2011 at 9:43 AM


Having thought a bit more and building on what I said about having a website build as the theme I think we would actually be missing a trick doing a "MusicStore" or "Contoso" - whats peoples thoughts on something like Cider store or something to do with Apples?

I also think the book needs to have one section (not just a few chapters) dedicated to the in-depth module development. If we analyse the forum posts, it's plain to see people's pain points and I feel the book needs to address these in detail to become a great resource.


Steve (ST)



Sep 10, 2011 at 10:14 AM

lol - Being from the south west of England I love a good old Cider!..

Agreed that the pain points that are brought up time and time again are something that should go in to this. I think the structure has to appeal to someone picking Orchard up and starting fresh because the biggest pain point is the learning curve.


Sep 10, 2011 at 1:37 PM
Edited Sep 10, 2011 at 1:39 PM

Great idea!

Sep 10, 2011 at 1:39 PM
Edited Sep 10, 2011 at 1:40 PM

Bertrand this is a fantastic idea and I'd love to get involved. I like the idea of building a site - having some official documentation on writing a content item with multiple parts, implementing widgets etc would be really valuable as while the current documentation is good, it is quite focused. Personally, I would have found it really useful to have some documentation on how to write my own admin controllers "The Orchard Way", extracting lists of content, displaying lists of items (and paging!)

While it is not public I am the lead developer on a project (which is in fact a redistributable product) that has over 20 custom modules with many of them focused on the admin dashboard rather than the front end, so this really is an area where I can contribute some of what I've learned.

My google docs Id is perspectiveuk at gmail dot com.

Sep 10, 2011 at 8:28 PM

I agree with Sebastien - Let's do 2 volumes. Both would be very useful for the community.

Sep 11, 2011 at 6:57 PM

LOL. I can tell you that when we built the Orchard Gallery site, one of our first designs featured apples on the home page. It was decided that wasn't a good idea to feature Apple(s) for a project started and sponsored by Microsoft, and built to encourage use of the Microsoft platform.  :-)

Sep 12, 2011 at 3:01 PM

Very cool idea!

The concept of two-volume set looks nice - we clearly have two separate groups of different users - those that simply need to quickly setup a site using available goodies (which I suppose are the greatest one) and those that build something complex on top of the framework. But we also have a third group - much underestimated in my opinion - the designers. They fit rather in the developer's group, but have clearly a different point of view.

That being said I guess it'd be good to divide the Shapes section in two (maybe pushing a part of it to a third, smaller volume?) - one for the devs and one for the designers. Shapes itself are a really wide topic and one of the most problematic core concepts - a detailed description would be much desired, I guess.

Bertrand, what's the planned ETA and timeline of the first version of the book?

I'd like to commit to writing chapters about Drivers, Handlers and Event Bus (from the developer's side) and possibly co-authoring Shapes and/or Filters, and/or Overriding existing functionality chapters (from the Advanced Concepts part), but that depends on when does it have to be ready (at least roughly estimating).

@Kevin - Yeah, Apple(s) don't seem to be a good idea... Maybe something thats "micro", "soft" and grows in orchards;) Cherries?


- Piotr


Sep 12, 2011 at 4:13 PM

I am following the Orchard project for a few months already since I came across it

Unfortunately however, I have too much work at hand so I didn't find the time to dig into the platform and learn how to use it to build websites which are not trivial.

It would be really AWSOME if I could just buy a textbook that explains the whole thing in a structural manner - from the basics to the most advanced issues. 

Great idea. Go Go guys. Looking forward.

Sep 13, 2011 at 11:54 AM
Edited Sep 13, 2011 at 11:56 AM

Count me in as well. It'll make a nice change from the in-depth technical posts I'm writing on it now! I'll have a look and see what bits would be best for me to concentrate on.

My Google Docs ID is andrew AT xyncro DOT com

EDIT: Edited to add that I see you have a big set of headings there around the internals - I'll commit to writing some of that (although maybe not in quite as much code following detail as my blog posts, unless people want that!)

Sep 13, 2011 at 9:35 PM

@Piotr: let me quote the great Douglas Adams: "I love deadlines. I like the whooshing sound they make as they fly by." I don't think we should impose ourselves a deadline. the book will be done when it's done. So no planned ETA. What is your Google id? Cherries sound fine to me.

@kolektiv: you are in.

Sep 13, 2011 at 11:36 PM

@Bertrand: Sounds great! Love the no-deadlines approach:) My Google ID: piotr dot szmyd at gmail dot com

Sep 14, 2011 at 12:14 AM

As the co-author of NHibernate in Action, I can hopefully make some contributions.
So, count me in.

Have you thought of the organization around this project? And the tools?
My suggestion would be to setup a CodePlex project and use a markup language like DocBook. Or we can use a wiki if we want something simple (transforming it into a pdf/print book will just be a bit harder).

Pierre Henri - phkuate(at)

Sep 14, 2011 at 12:26 AM

You are in. I haven't looked at DocBook but it looks like a good idea. Someone should also go ahead and open a new CodePlex space for the source code accompanying the book, as well as maybe media.

Sep 14, 2011 at 12:27 PM

I'd like to collaborate if I can help in any way on this project.

Google id : agriffard at gmail dot com

I don't know if my writing skills in English and technical skills on Orchard could allow me to contribute to a part but I can help for reviews, suggestions, sample website, ...

I'm asking myself if a French translation could interest some people ?

It would also be nice to have translated versions of the Wiki (

The simple fact to try to translate the concepts used in Orchard into French words (parts, tenants, content type, ...), is difficult.

It is not easy to find the good expressions and words that express these concepts, keeping the initial meanings.


Sep 14, 2011 at 8:23 PM

Antoine, I added you to the project. On concept translation, your best bet is to try to be consistent with what the po files are doing.

Sep 16, 2011 at 11:12 PM
bertrandleroy wrote:

You are in. I haven't looked at DocBook but it looks like a good idea. Someone should also go ahead and open a new CodePlex space for the source code accompanying the book, as well as maybe media.

If we go with DocBook, that CodePlex space will actually contain the book itself as well (DocBook files are XML).

For the process of writing the book, I would like to suggest the following: We have contributors of various levels and available time, we also want a community-driven book. So we should have a way for everybody to participate in the process of making this book happen. And the way it could work is if we use this discussion forum.

Basically, we would have three types of contributors: The editors who plan the book structure, organize and manage the overall book writing process. Then, they put together a table of content (short at first and growing as we progress). Each line in the table of content is a chapter's section and it is linked to a discussion topic on this forum (in a new category). The writers can pick one of these sections, go in its discussion and write a draft of that section. The reviewers are normal users who would use that draft as documentation and who will comment on how it can be improved. At this stage, we will focus on getting raw content with little focus on formatting, etc.

When the editors consider a topic's draft to be mature enough, they will take its content, re-write it into DocBook format and commit it. That's where we will make sure that we have proper formatting, images, code samples, etc. (*)

On top of getting content from the community, this process also lowers the barrier of entry to contribute. Only editors are project developers who must know how to write in DocBook format. Anybody on the forum can be a writer, even if only for a day.

We will also have scenarios where a user asks a question on this forum, and the discussion that ensues is so good that it gets rewritten into a section of the book. The same way, blog posts could be donated by their authors to be included in the book. We will then encourage any question/blog post to be written in such a way that can easily be integrated into the book...

I'm also thinking that we should use the issue tracker to assign specific tasks to editors. Like: "Add screenshots to this section", "Rewrite this discussion into a section", etc.
This would ensure that we have a way to track who is doing what and keep everybody motivated to move forward.

So far, we treat each section as fairly independent (it helps to keep things simple and scale). At a later stage, we will have consolidation processes where we rewrite a few lines (mainly the beginnings and ends) to make the section fit well with the other sections of the chapter. Then, do the same at chapter level.

And the last stage will be a more formal review process where we ask people to read the chapters and give both global and local comments. We can do that for each chapter, then again when the whole book is close to completion (ie: v1.0).

Pierre Henri.


(*) Once a section gets into DocBook format, it becomes harder for reviewers to proofread and suggest changes (like fixing typos, rephrasing sentences, etc.). What I'm thinking here is that we would have a continuous integration server that would generate the html version of the DocBook and make it accessible to the public (every night). In a way, it would become like the replacement of the current documentation wiki. These html pages must be presented in a way that can be inline-commented. I'm not sure what tool would allow us to do that, but I'm sure there is something like that out there. The ideal would be something exactly like the Track Changes feature of Office Word. If that platform is really good, maybe it could be the one writers and reviewers use from the start instead of the discussions forum...

Sep 16, 2011 at 11:22 PM

All absolutely excellent ideas. Pierre Henri, do you want to take the lead on this? I had assumed I would do it but if you want to, I have no problem with it :) and lots of other things to take care, so boredom won't be a problem.

Sep 16, 2011 at 11:41 PM

I am sckeptical with the xml usage. I also think we need to specify the content in a reusable format, but xml will be cumbersome. I would have preferred a format like markdown. But I know that it might not be adapted for books, so ... But I am sure that at some point we could export the whole content to docbook.

For instance, the Nuget documentation is handled like this. a Codeplex project contains markdown, and the application renders it as a website. Maybe we could have a solution like this one, where we edit markdown (because it's simpler than XML), it's rendered in its own web site (taking the idea from nuget, open source), and we could even add our own notations to include code blocks like it's done for external images. This could enable some preprocessing and we could see the result in the live application. And we still get the DVCS goodness.

NB: definitely not to be done in Orchard, but as a straight MVC app. The big difference with a wiki is the file based logic, using dvcs for merging/branching work.

Sep 17, 2011 at 12:09 AM

@Bertrand: Sure, I will keep posting my thoughts on a few more topics, then we can take it from there.

@Sébastien: I took a look at the Nuget doc project, it is great. They have already figured out all the setup and contribution processes. So, I'm happy if we go that way.

By the way, for proofreading and reviewing, I tested Google Docs, and it allows you to upload a whole folder full of web pages, making it accessible to the public. And any signed-in user can edit the pages. The downsides are that it is a manual process and it doesn't handle linked files (images and css)...


The next question I am wondering about is the content of the book and the current TOC. Since everybody here likes the idea of building sample website(s), I would suggest changing the TOC to be more scenarios driven (so it feels more like a story). I will propose my changes when I have something concrete.

We may end up with different books for website admins, theme designers and module developers, but let's start with all this as one and split when we have enough content.

Sep 19, 2011 at 8:18 AM

already learned something from the book! keep up the good work!

Sep 19, 2011 at 6:15 PM

Hi Chaps, could you please include my id. Jetski5822 at gmail dot com

Sep 19, 2011 at 6:25 PM

You're in.

Oct 4, 2011 at 10:39 AM
Edited Oct 4, 2011 at 10:40 AM


I'd like to be included

carl.bm2007 at

Oct 5, 2011 at 7:33 PM

We'll be moving the existing work to the new infrastructure that Sébastien built using CodePlex/Mercurial and Markdown.

If you are interested in collaborating to the book, please clone the repository that can be found at: We will give some additional details soon, but suffice it say for now that you can just write locally, then submit a patch like you would for code contributions (no need to be registered on the project, having a CodePlex account is enough). The book is split into small pieces that can be worked on independently.

I will be retiring the Google Docs version.

Oct 8, 2011 at 11:02 AM

I wouldn't mind contributing something, but it would have to be non-technical. I personally think the current documentation is too technical and it sometimes takes a long time to figure simple things out. I'm using Orchard to host my own site and thus my experience is real-world.

I realise that Orchard i good technically and am impressed by it in that respect. However I also believe that it should be as accessible as possible to non-technical people.

All I think I could offer is to write a chapter about my experience of using Orchard (hosted in Azure) and try to explain the problems I encountered and how I overcame them (or didn't...). This may not be the type of content you need or have in mind though.

Oct 8, 2011 at 9:36 PM

Sure, that sounds good.

Oct 9, 2011 at 3:43 PM

I don't know how everyone else feels about this, or whether or not it can be debated as to whether or not something like this belongs in a CMS such as Orchard, but from my limited experience with Orchard and reading around, it seems like it would be capable of CRUD functionality. Mayhaps this would warrant an underlying theme in the book, otherwise a chapter about how this could be implemented? I am looking into building modules that would capture data from clients.  I have some experience with this in MVC, and just personally am trying to get my head around Orchard's underlying structure to accomplish this. Just a suggestion.

Oct 10, 2011 at 8:29 AM
Edited Oct 10, 2011 at 8:31 AM

I'd also like to suggest some more philosophical/architectural topics. We've just delivered a site (link soon :) and are most of the way through a second one and have started a third - and there are *loads* of things that I've learned in the process. Most where I/we've done a lot of rework after gaining the experience.

  • Only use modules when the existing infrastructure absolutely cannot support what you're doing - KISS.
  • How to architect data access to allow for caching (I needed to rewrite all our widget drivers to cache POCOs for instance).
  • If you're working in a team some ways of working together for the 'back end' and HTML devs depending on how you've worked previously.
  • And I could probably go on :)

Of interest?

The subjects could be included in the relevant sections, but personally I get frustrated by books that do this. They force me to read the entire book to get some nuggets of knowledge when I could just read a single section.

Oct 10, 2011 at 8:09 PM

Absolutely. The team organization thing in particular seems very important.

Oct 11, 2011 at 7:01 PM

I would like to suggest that a chapter describing what a Content Management System (CMS) is (and is not) would be highly desirable, particularly for non developers.

Jan 25, 2013 at 10:25 PM
Edited Jan 25, 2013 at 11:08 PM


Has this project died out?

The book seems a bit thin and last post here was over a year ago! The repo seems a bit inactive also.

I have just recently fallen in love with Orchard (excellent work, beautiful architecture!!), and I'm planning on making this my default cms.

I've done my share of technical and scientific writing and I'm willing to do this properly and in an organized matter if I know that I can get some minimum support and answers to technical questions.

If the project is still ongoing, can someone update me?

Jan 31, 2013 at 8:55 AM
It hasn't been active lately, no, but it would be great if someone with more time could take the lead on this.
Feb 1, 2013 at 12:16 PM
Sure, I'd love to contribute something.
And this is also an excellent way to learn the tricks and turns of the system!

As I said, the progress of the work is dependent on the availability of resources of the subject that will be covered, and that the community is active enough to provide corrections/reviews and support on topics that aren't well documented. (I'm relatively new to Orchard, but I'll catch up quick)

I'll build on some of what has been done so far (outline of the work, etc).
I'll also keep the work available to everyone.

I would prefer to write the book using LaTex, I'm sure that this will not hinder anybody in getting involved if the project gains momentum again.

Should I use the existing repository for the work or should I start a new one?
Any preferences on where to place the source?
Feb 10, 2013 at 8:34 PM
Oh my, LaTeX. Haven't touched that for about 20 years. It is not a widely used technology in the dev community. Can we stick to Markdown?

Let's use the existing repo if you don't mind.
Feb 10, 2013 at 9:02 PM
LaTeX rocks!! - I was thinking about doing my CV in it. However, we should stick to Markdown.
Feb 10, 2013 at 9:05 PM
Edited Feb 10, 2013 at 9:05 PM
Oh yes, LaTeX is awesome. HTML still hasn't caught up with its spring-based layout for example. The issue here is not awesomeness but familiarity.