The Orchard Book

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 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.

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.

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.

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.

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 …

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.

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.

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.

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. :-)

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).

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!)

@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.

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).

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...

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.

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.

@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.

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:
https://hg01.codeplex.com/orchardbook. 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 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.

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.

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.

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?