Documentation wish list

Topics: Announcements
Coordinator
Dec 8, 2011 at 9:31 PM

I'm starting some documentation work, and I wanted to get a feel of what people would like to see written as new topics, broken stuff that needs fixing and so on. Please answer with your suggestions.

Oh, and just so you know, our documentation, like everything we do, is open source. Feel free to participate at https://github.com/OrchardCMS/OrchardDoc

Dec 8, 2011 at 10:13 PM

I'm just started using and learning Orchard.

My first suggestion would be: focus on 'newbies' like me and the problems we have.

I'd would like to share my experience, maybe that is some inspiration for documentation.

I installed Webmatrix on my pc, started discovering orchard. Followed the excellent documentation on how to create a child theme and I've started to customizing my child theme (which is based on the default theme).
Everything worked fine and I created a basic website and suddenly my boss tells me it looks good and it needs to go live.

Then I had several questions:
I have a collegue, who needs access to the website in case i'm on vacation or sick.
- So how do I share my local orchard code which runs in webmatrix with him? should I just put the code in a zipfile and send it? should I publish to his pc?
- If I publish my site to a production server and I need to do an update, should that be done directly on the production site
or on my local site (but this might overwrite or conflict with my production site database?)

In general, by doing this for the first time, it would be nice to have some good practical examples on how you do these things. (eg. 2 people with each a development pc and a production server).

----

Some documentation on creating (sub)menus would be helpful.
Let's say this is my menu:
1 Home
2 Products
2.1 ProductA
2.2 ProductB
3 About

I want to show items 1 2 and 3 on my horizontal menu
When clicking 2 (Products) I want to show items 2.1 and 2.2 on a vertical menu on the left side instead of on the horizontal main menu.
While I'm on page 2 (Products) and I click item 2.1, I want this vertical menu to be still available (because I want to be able to switch from productA (2.1) to productB (2.2)).

It would be nice to see how the orchard theme suggests us to do this. Should a second menu be created? Do you have to put that on a product layer with a specific rule? ...  I could find none or very little information about this. Something I thought that was easy to create.

----

Recovery, failure information:

- information on how to easily backup and restore orchard. Which files are important.

- Information on how to recover orchard. Lets say I installed the url rewrite module and I have made a typo in my rule and I'm unable to access my orchard admin panel anymore. Information which files we could delete (if that is possible). Could we delete the module directory and will it be fixed?
(ps: yes I was so stupid enough to have this problem and created a new orchard setup :p )

---

Playing with layers:

- i've added a breadcrumbs widget on my site on the default layer. is it possible to hide a widget for a certain layer (like thehomepage layer?) because I don't need my breadcrumbs there? An example would be great as a starter.

---

- Maybe some extra examples on how to add layer rules.

---

These are some problems I've experienced as a beginner. I was looking for answers on these questions which I could not find directly. I hope this is some inspiration for writing documentation.
I want to help writing some information for starters, but first I need to discover and use orchard a bit more.

(ps, it's me, teusje :))

Dec 8, 2011 at 10:54 PM

From a recent discussion with another user, I think a good move would be starting with a rundown of all the important concepts specific to Orchard's content/display framework: Items, Parts, Widgets, Handlers, Drivers, Placement, Content Manager, Queries, Stereotypes, Display Types, Shapes - in roughly that order, with links to more detailed topics on each and how they relate to each other. I think this would help people get a quicker overall understanding of how everything fits together. A lot of this information is present in the documentation, but it's not really presented in an ordered fashion that properly introduces each of the concepts, they just turn up as you go along. I notice quite a lot of discussions revolving around users not fully understanding one or more of those concepts and it would be good to be able to just say "this link explains everything" :)