Towards better documentation

Topics: Administration
Oct 18, 2012 at 4:30 AM

Picking up on the recent exchange re: the state of documentation...

I think the single biggest weakness of the collection of documents currently functioning as 'documentation' is the lack of explicit context. Orchard will be view very very differently by a developer with in-depth knowledge of mvc and asp.net code who can step into commented code and understand stuff vs. someone i'll term 'builder' who is going to be constructing a site by the Admin UI.

The few archival documents that have first tier links are distracting by not being dated but they could be really valuable if they could be re-visited by the originator (b.) and annotated with statements like 'this priority was a) abandoned because.../b) worked out really well as can be seen in module...c) is no longer operative because asp.net framework sucks/changed/I got smarter. (on the other hand - in terms of prioritizing [shrug] interesting? or productive? [more shrug]. if not worth revisiting then lets cull them.

I think both groups (builders and coders) would be best served if the documentation made clear which audience was being addressed. 

To those finding b.'s tone abrasive - yeah, agreed, he'd come across better if he typed with a British accent but what do you expect - he's French. and basically correct. Premo documentation would be nice - but it's better than it was a year ago while the code is heads and shoulders better - proof of the pudding and all that.

All in all I suggest a more explicit 2-track approach with docs - one for coders and one for builders. (& extra credit for english accents).

Coordinator
Oct 18, 2012 at 5:04 AM

Yes. We've tried it in previous iterations, but let's try it again: let's make documentation a feature of 1.7, with a work group focused on it. I'm in. Who wants in as well?

Developer
Oct 18, 2012 at 5:31 AM

Great idea, count me in.

Developer
Oct 18, 2012 at 11:32 AM

I'd like to contribute too.

Here are some ideas :

- Documentation could be reorganized to target different profiles : Developer, Designer, Administrator, User

- One the most used modules of Drupal is the Advanced Help (http://drupal.org/project/advanced_help ) that seems to allow the developer to provide an internal help (indexed, searchable, ....) and a documentation of the features.

- The description Module.txt file is too small to explain how the module works.
May be, just a Help folder with Markdown or txt files like ReadMe, Changes (Version history), ... would be interesting at the root of the package. 

- WordPress also seems to have an internal help (expanding panel, contextual to the current page) and specific support (http://en.support.wordpress.com/) and learning sub-domains (http://learn.wordpress.com/) .

- Instead of the page 'Discussions and Help' (http://orchardproject.net/discussions), we could have a page named Support with this links :

Documentation = docs.orchardproject.net
Forum = CodePlex Discussions, StackOverflow Faq ?
Communities (In other languages) = links to communities and specific localized categories in the discussions
Articles = pages with a projection of External links on the homepage
Videos = http://docs.orchardproject.net/Documentation/Orchard-TV
Books (when there will be more ?)
Online training = Pluralsight, ... ?
Professional services = link to 'Job Offers' categories ?

I don't know if Chat and Mailing List are often used.

 

Coordinator
Oct 18, 2012 at 5:04 PM
Edited Oct 18, 2012 at 5:04 PM

Thanks guys.

First, I think we need to refresh the existing documentation. If you agree, how about we each commit to taking a letter and start reviewing each document in alphabetical order? I'll take A. When we're done with a letter, let's come back to this thread and take another one (or more) and declare it here (so as to avoid duplication of effort).

Things to look for: obsolete information, incomplete information, missing information. I'd also like us, while we're there, to refresh the markdown a bit, as most documents are straight imports from the wiki and tend to have overly long lines. As Markdown doesn't care about single line breaks, let's make it more readable from a text editor, as that will help future updates.

I recommend cloning the repo locally and working with an offline markdown editor such as this: http://visualstudiogallery.msdn.microsoft.com/0855e23e-4c4c-4c82-8b39-24ab5c5a7f79

Totally agree on different profiles. Let's annotate each document with the target audience(s). Not sure yet what the best way to do that is, but I'll come back with a solution.

Let's review what Drupal is doing as well, as Antoine says. I'd love to have a standard shape that devs can use to point to online documentation. This could be another output of this group. About the manifest, can we decide that the web site attribute should point to the documentation? Why don't we have that link displayed in the list of features? Should we have a link per feature rather than one per module? I also like the idea of a conventional readme.md file at the root of the module. It's the convention that GitHub is using and it works remarkably well as it encourages module authors to provide even minimal documentation with a very small amount of effort as all they have to do is write a file. No web site to set-up or anything like that.

Changes to the web site are another subject we should start tackling. There is a number of improvements I'd like to make, and it will happen, but the documentation is a higher priority.

Cheers!

Oct 18, 2012 at 7:03 PM

yes, count me in guys, I specifically like the target profiles: Developer, Designer, Administrator, User

Admin and User would really only be the ones that would need translations, the others could remain in English, therefore I also would like to contribute with the Portuguese version for them.

Coordinator
Oct 18, 2012 at 8:17 PM

We all agree that we need the documentation to be have a progressive orientation, which tells a story.

It happens I already had worked on such thing for Orchard, so here it is. The goal is to have something that you can read like a book, with understanding what is Orchard to hosting your website. It would also have specific chapters for Module development which are not covered in the current proposal.

My initial thoughts and goals :

This documentation is intended to website professionals who want to understand how Orchard can help them create websites more quickly, and maintainable by their customers. The goal is not to explain how to develop custom modules but how to simply create websites It might need some little programming/scripting knowledge though for some specific parts, like theming.
- It is intended to all web professionals, like web developers and web designers.
- This is not a quick start documentation for creating a simple website, but will instead explain the concepts and philosophy behind Orchard in order to provide a clear understanding of all its tenets.
- There might be an advanced section explaining all the specific APIs available and how they can be used to create Modules.
- The documentation will go through all the concepts based on the creation of real websites, step by step. For instance, the introduction might describe how to install a module and change the theme from the gallery, by creating a brochure website or a simple blog. Then adding widgets and pages, introducing Orchard concepts.
* e.g., Blog engine (widgets, pages), Brochure Website (contact form, google stats, SEO), Article management (taxonomy, output caching). Or it can be a single website representing all those concepts
- It will go through all recommended modules to do specific tasks, like taxonomies, combinator, google stats, SEO, output caching.
- Because we don't target C# developers, we might want to focus on using WebMatrix, and not using TortoiseHg/Visual Studio

 

Introduction to Orchard

Requirements

Downloading

What is a CMS ?

Why Orchard ?

.NET

ASP.NET MVC (clean HTML)

Extensibility

Online Presence

Website

Gallery

Forum

Codeplex

History

Outercurve

Microsoft

Steering committee

 

Managing content

Pages

Blog

Widgets

Comments

  • Integrated
  • Facebook
  • Disqus

Custom Content

  • Types
  • Parts
  • Fields

Navigation

Media

Publishing/Archiving Later

 

Image Gallery

Layer

 

Categorizing Content

Taxonomies

Projections

Tags

Lists

 

 

Social

Profiles

Stars

 

 

Theming

 

Using an existing theme

Customizing themes

Creating reusable themes

Shape Tracing

Shapes

Resources

Zones

Alternates

Views

Mobile

 

Search engine

 

Security

Users

Roles

Permissions

 

Localization

Multi-lingual websites

 

Rules

Sending emails

Tokens

Closing comments after some delay

Workflow

 

Forms

Contact Form

Content Submission

Anti-Spam

 

Optimizing

SEO

Caching

Bundling

Sitemap

Robots.txt

Rewrite Rules

 

Deploying your Website

Import/Export

Recipes

Hosting

Public hosting

PAAS

e.g., GoDaddy, Azure

IAAS

e.g. , Amazon, RackSpace

Private hosting

Topologies

Warmup module

Tenants


Oct 18, 2012 at 8:23 PM

@justSteve

>he's French. 

nobody's perfect :)

>and basically correct. Premo documentation would be nice - but it's better than it was a year ago while the code is heads and shoulders better...

Sounds like some reality distortion :) Those assertions are indeed correct but that was not the point ...

Anyway, let's see if I can provide a few hints that could be helpful.

If you ask me I believe there is a need for complete reorganization.

The current structure / categorization is confusing. For instance, "Orchard Concept Definitions" under About the Project at the same level that "What's Happening now" makes it think that this information is optional... this is not and one should read it twice or even 3 times (unless maybe you just want a blog with a few pages - OR - if you are using a ready made site) ... it should be part of the Getting Started section...

There is a need for more documentation levels. For instance when you have a look at the Getting started section, the first 3 links are variations on installing Orchard. Moreover, the wording is confusing because the first link "Installing Orchard" seems like generic and one would expect having all the options described there... then the third link is "Working with Orchard in WebMatrix" when it should be "Installing and working with WebMatrix"... I know it's not that much but it counts... Anyway there should be just one 1st level entry for Installing orchard... and all the options in a second level ... 

Now what is under Documentation would also need as serious rework in terms of organization. When learning some tools, product, it's important to be able to have different levels of reading (more complex stuff could be red/handled at a later time for instance). There should also be some reading guide. The way it is currently feels like some guys have written some articles to explain some features. Those articles have then been categorized in two levels and that's it... 

For instance you have "Customizing Websites" and "Using the Orchard Gallery" at the same level... with what seems like more information for the Orchard Gallery. It doesn't sound like well balanced. Using a gallery is overall straightforward and moreover you can find the necessary information in "installing and Upgrading Modules" under "Managing Websites"... It's not like the "Using Orchard Gallery" information is not interesting at some point but it adds unnecessary annoyance while going through some learning process....

Even within a First level theme/feature, it often sounds like a collection of articles that fits that particular theme and not like some real documentation that proposes a clear path to learn how to use that features.

I completely agree with @justSteve with the two level of readings for "Developers" and "Builders" (and even if you are a developers, you may not necessarily want to add custom types programmatically - or you don't know for sure because it may depends on what the admin interface has to offer in terms of flexibility). Anyway by having this two level of reading, would avoid unnecessary confusion.

Reference documentation is completely lacking. It's really frustrating to go through all the documentation just to realize that this option is not documented anywhere. And frankly, going through the source code in order to try to understand what is some option or setting made for does not make sense... Reading and understanding some source code can take a lot of time and unless you have decided to invest deeply into orchard this is a real show stopper... Unless, it's completely obvious, everything should be documented - or at lease, the entry should be there so that someone can come in and complete the documentation. The existing articles could certainly fit within a documentation that has a more "Reference" tone. Once you have read some introductory articles that explain the concepts, I'd rather have a documentation more straight to the point. 

Menus
1.5.1 - this information applies to 1.5.1 only due to a major rewrite (for previous versions see ...)

  • Concepts
  • Creating menus and submenus
  • Developer's corner

Content Types

1.5 - Feature Y added
1.4 - Feature X added

  • Concepts
  • OOB content types
  • Custom Content types
  • Developer's corner: creating content through code

Lists
1.4 - We recommend using the new Projection/Queries features whenever possible. 

  • Concepts
  • ...
  • ...

To summarize:

  • A complete documentation reorganization
  • A more in-depth Starting Guide - not just a few articles here and there but some real work on how to introduce Orchard and to provide the newcomer with a learning strategy.
  • A more systematic approach and methodology so that it is easier to discard obsolete information or at least so that the user know the information may be obsolete ...

Obviously, other existing CMS project documentation can help for getting interesting idea...

Oct 18, 2012 at 8:40 PM

@sebastienros

That's it ... 

Oct 18, 2012 at 9:42 PM

Why documentation couldn't use some 'taxonomy filter' allowing to select:

- skills: basic/admin/starter dev/skilled dev

- versions: 1.4 /1.5/1.6......

- level discovery/normal/detailled

etc.

Developer
Oct 18, 2012 at 10:01 PM

FYI Orchard docs runs on an ASP.NET WebSites site, so no Taxonomies or other Orchard stuff there. However here I see an opportunity to cooperate: I have a documentation display module in mind for Orchard Hungary that would pull in pages written in Markdown from a repository. Any thoughts?

Coordinator
Oct 18, 2012 at 10:12 PM

"I have a documentation display module in mind for Orchard Hungary that would pull in pages written in Markdown from a repository." What a brilliant idea, why don't we have that already !

Snap, we do ;)

Developer
Oct 18, 2012 at 10:16 PM

Wow, really? I mean, as an Orchard module, because that's what I've meant? :-)

Coordinator
Oct 18, 2012 at 10:36 PM

Sorry, didn't see that, so my corrected answer is: Why do we want a module for that ?

;)

Zoltan, don't you some homework to do ? Or you really never sleep !

Coordinator
Oct 19, 2012 at 8:15 PM

After some more thoughts and looking at some other examples like this one http://hgbook.red-bean.com/ or Drupal documentation, it seems the most important thing to do is to provide the TOC when reading an article, and also give simple links like Previous / Next to read the documentation in a meaningful order.

This implies two actions:
- define a toc with some progression
- improve the current contextual toc to add navigation to next/prev article, and optionally show the broader sections

I would suggest to do it in this order:
- define a convention for the official toc document, so it can be used easily in the script or as a server side script to be rendered contextually
- when it works, reorganize the toc to provide some progression, I gave my take in a previous post on this thread
- take every content from the current documentation, and place it in the updated toc 
- review the content, and update it, or suggest new chapters in the toc to fit it in, or remove if obsolete/useless 

 

 

 

Developer
Oct 19, 2012 at 8:29 PM

Oh OK :-). I'm having the following on my mind:

  • Having a repo for documentation-like content, because vcs are great at that (especially that there would be some code in the repo as well; non-running though, also for documentation)
  • Open for contributions from developers (or at least very techy people; Git or Mercurial is no problem here) through pull request or even having forks for maintaining multiple coupled, but different content sets

Now this all is the same idea what's behind Orchard documentation. But I'd like to have Orchard's services behind this with all the goodies it can offer. Even tags for example (this complicates the solution because there'd be a need to represent documentation pages somehow as content items too, what can be messy). Even if the whole module is just a viewer for the repo it has the value of better integration with an existing Orchard instance (no need to setup an application and subdomain for the WebSite, there's no additional theme maintenance as the functionality can be installed just as any module).

Now this inherently includes the idea of kind of an Orchard-based wiki engine, but I like the repository-based better.

I'd do need some more sleep! :-D

Coordinator
Oct 19, 2012 at 8:37 PM

I don't think we should spend some time on a module. Too much effort, can have bugs, and we might have to handle authentication and give access to the dashboard. The current implementation works very well, we should continue with it. My own opinion though.

Oct 19, 2012 at 8:45 PM

I also don't think we should spend time on a module. Time is a limited resource and the point of this thread is to devote some of what little time we all have towards documentation rather than code. We have documentation debt that is higher than the need for a fancy docs module. 

Oct 20, 2012 at 9:38 AM
Edited Oct 20, 2012 at 9:38 AM

Back to sebastien reorganisation and topics, I'll split the documentation into 2 bigs parts : "user/builder/admin" and "dev". The "dev" part should be covered in another discussion.

The TOC proposed by sebastien looks great. I think the "Getting Started" should still exists in the form of a simple workflow to install an orchard website from scratch and deploy it on an hosting solution (or use it locally). Perhaps in an unique page to describe all steps : The goal is to allow someone which want to read doc topics to use an installation when reading for testing purposes.

Developer
Oct 20, 2012 at 10:03 AM

@Sebastien: alright, I wouldn't do for the Orchard docs alone either. I'll see whether in the end I'll work on such a module and ask you if it'd be interesting to integrate into the Orchard docs.

Oct 20, 2012 at 1:04 PM
Edited Oct 20, 2012 at 1:04 PM

 

FredericLatour wrote:

@justSteve

>he's French. 

nobody's perfect :)


I maybe should have made clear that much of what I know about the interplay of nations comes from having been a teenager when Monty Python Holy Grail was on first run. The residues of those english actors doing French accents is hard to shake. ;)

But seriously - hat's off to those of you who are non-native English speakers and having to code in English - much less handle the nuances of documenting the code.

....

I'm in a position of contributing to better documentation by the fact that I need it desperately right now. I'm digesting what exists and understand the personal benefit of re-writing and copy editing and occasionally whining about the current document set.

So in that context I need some guidance with setting up for local editing and interacting with the repository. Up to this point I've make a couple edits via the online editor but I'd really prefer to work locally.  I've downloaded the recommended markup editor - I need a bit of help wiring up my VS with the Docs repository. I've been a standalone dev forever and the ways of your GitHubs are as a foreign language to me.

thx

Oct 20, 2012 at 4:23 PM
styx31 wrote:

Back to sebastien reorganisation and topics, I'll split the documentation into 2 bigs parts : "user/builder/admin" and "dev". The "dev" part should be covered in another discussion.

How about as a step along the way of splitting stuff up - while looking at docs and wondering 'which bin? dev or builder' you'll see lots of places where they mix - a couple paragraphs of interest to dev, and then a few passages or links that speaks something to the builder. Should be a way to 'sub-tag' document parts.

Suggest that the top-level view  provided in the existing root becomes the target of those tags. Let's put a pair of links at the bottom of each section 

  • Dev
  • Builder

So we end up with a great jump off point - the one place where those core ideas of Orchard are summarized - the table of contents hits all the notes and the info is presented in summary format really well (i think). If each of the sections lead me to more targeted, details documents and procedures I'd feel much better served. It's a great summary document in that it leaves me wanting more. And here I'd love to give you a more detailed visual of what I'm talking about by, say, editing the page itself and asking you to review but 'Edit' button [ahem] 404s.

 

Coordinator
Oct 20, 2012 at 8:36 PM
Edited Oct 20, 2012 at 8:37 PM

@justSteve: the GitHub client for Windows may be the best fit for you to interact between your local clone of the documentation site and the GitHub repository.

And when you hit a 404 on edit, it can be simply GitHub being over-sensitive over casing. You might want to look for a file that has the same name but differing by casing. I'm not sure why we have those differences.

Oct 21, 2012 at 1:25 AM

I believe there are mostly 3 possible approaches to Orchard:

Blog or simple Web Site

One may just want to set up a blog or a simple web site (blog + a few web pages) as fast as possible:

  • installing
  • creating a blog
  • creating pages
  • a few other concerns like selecting a theme, anti-spam, caching and the guy is ready to go

The guy should be ready in a couple of hours... This approach could be addressed specifically in the documentation: maybe a very specific chapter in the Getting Started.

Full CMS use without custom development

More complex needs. However the guy expects to achieve everything through the admin tools:

  • creating content parts, content types, queries, projections, forms, taxonomies
  • configuring routes,

This approach may still need some light development for writing alternate templates...

Full CMS use + development

Same as above + module development.

Please note that one may develop a module in order to implement new features but also to gain additional flexibility (in comparison to use the admin interface) when creating parts, content types,etc ... 

Oct 21, 2012 at 3:14 PM

I just encountered Orchard about a month ago and I really struggled with the documentation (which helped me because I then realized how important documentation was for a new user and I then spent a lot of time adding documentation of my product to my new Orchard web-site  :-) ).  I came to Orchard because I needed a web-site for my Windows Phone app and I wanted to use a CMS built on Microsoft technologies.   I tried several, and found that Orchard was a perfect mix of easy to use while allowing a developer to get under the covers.

Anyway - I would like to "give back" to the Orchard project and help out with the Orchard Documentation.  I am a long time microsoft developer, but was more of an ASP.Net webforms person (I am just wrapping my head around MVC).  Eventhough I spend every day working in Visual Studio, I was not able to get Orchard and Azure web-sites working together using Visual Studio (I ended up going the Web Matrix  route, which was a delightful experience). 

My point is that I am an Orchard  and MVC novice, and as such, I don't feel comfortable writing new documentation.  But I would be more than happy to review, edit, whatever you guys think I could do to help out.

Coordinator
Oct 21, 2012 at 7:30 PM

Reviewing and editing is a great start. Another thing could be to write more end-user oriented topics, or to verify older articles for obsolete parts. Thanks for offering to help.

Oct 21, 2012 at 8:10 PM

I'd be happy to check parts of the documentation that I have actual experience with.  I know you had suggested an alphabetical approach, but I'm not up to your speed.  I have done almost everything in the following sections of the documentation.


- Getting Started

- Customizing Websites

- Managing Websites


So I would be happy to work on any of that (just give me an assignment).  However I don't know what you mean by "cloning the repo locally" in the
following statement:
 
"I recommend cloning the repo locally and working with an offline markdown editor such as this: http://visualstudiogallery.msdn.microsoft.com/0855e23e-4c4c-4c82-8b39-24ab5c5a7f79"

Also - as a newbie I have found the Export/Import module very useful and I think you should consider adding something like "Extracting and Restoring Your Content From the Database" as a Getting Started topic.  It's a very impressive feature of Orchard (it means a user doesn't need to know anything about SQL in order to get a hold of their content and save it in a way that it can be reconstituted into another site).

Coordinator
Oct 21, 2012 at 8:12 PM

That's great. If you don't understand cloning the repository, just work off GitHub, that's fine.

Oct 22, 2012 at 2:29 PM

I think the Azure section should include info not just on deploying, but also: debugging / running the app locally on the Azure Compute and Storage emulators, and also a section describing the differences behind the scenes on when you run on Azure vs non-Azure. We talked about a lot of this stuff in another thread last week --  the different types of storage (local, blob, SQL Azure, Azure Tables), and what is used for each, and how to check the debug and error logs. 

Oct 22, 2012 at 3:25 PM

Ok - I did a fork from GitHub and have a  local copy which I am editing in Visual Studio.    My plan of attack was to start with Installing-Orchard.markdown and to go through the instructions, take new screenshots as I go along, and update anything that isn't correct.  If that's not how you want it done, let me know.

Coordinator
Oct 22, 2012 at 6:00 PM

I think we'll have TheMonarch to be the owner of the Azure documentation ;)

Oct 22, 2012 at 6:19 PM

Sure, I'd be glad to do that. 

Oct 24, 2012 at 1:17 AM

@TheMonarch Let me know if I can help with Azure documentation. I'm running Orchard in Azure cloud services. 

Oct 24, 2012 at 4:05 AM
Edited Oct 24, 2012 at 4:08 AM

Definitely would welcome any help. What aspect(s) of Azure do you know best, or want to write docs for? Let's outline the sections, and then we can divide them. Here's a rough draft, feel free to edit: 

Orchard Docs -> Azure 

  •  Overview: What's different when Orchard runs in Azure
    • Storage (talk about blob/SQL Azure/Table/Local, and and what Orchard uses each one for -- cover logs, settings.txt, media, Lucene index, etc)
  • Building / Deploying (should they be separate?)
    • Web Role
    • Azure websites **  (FTP / Git)
  • Debugging
    • Running the Web Role locally, under Azure Compute/Storage emulators
    • How to check logs 
  • Customizing 
    • ServiceConfiguration.<Configuration>.cscfg, Orchard.Azure.Web/Startup/ConfigureIIS.cmd, etc

** I have no experience with Azure websites and no plans to try it out in the near future, so hopefully someone else will be able to tackle this. I think there have been some blog posts so hopefully one of those bloggers could contribute their content to the docs.

Maybe also a section with suggested minimum instance size/count, database config, or other things like that. Or those suggestions could be inline in the deploy section. 

Oct 24, 2012 at 7:39 AM

May be it should be in another thread, but concerning documentation, I have been used since years to read comments in source code, and there are quite no comments in Orchard source code. Is it a deliberate choice, some optimization need ?

Documentation in source had been usefull in the past, running some tools like castle to build dev help files.

Regards

CS

Oct 24, 2012 at 12:38 PM

Sign me up for the Azure Web Sites sub-documentation :)

This could probably go on another discussion topic but there are 2 methods for deployment, directly from the portal, of if you want to use Azure Storage you need to build and deploy from this fork: http://orchard.codeplex.com/SourceControl/network/forks/pnmcosta/azurewebsites

Not sure whether this will be a permanent option or not, whether it could be added to the core or not, but at the moment we could just just create a public GIT repo of a build from the fork above for GIT deployment as an option.

Pending for instructions? :)

Oct 24, 2012 at 4:16 PM
Edited Oct 24, 2012 at 4:19 PM

Great! So there are actually three methods of deploying to Azure websites right? Git, FTP, and directly from the portal? 

I think the next step is now people are cloning the docs repo from github and editing the docs. Then we send pull requests. Is that right Bertrand/Sebastien? 

Oct 24, 2012 at 5:12 PM
Edited Oct 24, 2012 at 7:34 PM

My level of familiarity with Orchard + Azure is as follows:

  • Deploying Orchard Azure Web Role via the portal 
  • Currently trying Orchard Azure Web Role deployment via Visual Studio Publish
  • Currently working on connecting Azure Connect to my Orchard Web Role
  • Used CloudBerry to inspect our Azure Blob contents
    • Blob contains Orchard.Web\Media contents/files, Settings.txt, iis logs

I'm also doing collaborative Orchard development using TFS as our shared source control. 

I'd be happy to contribute to any of these topics.

Oct 24, 2012 at 5:15 PM

I'm not in a position to help with the documentation, but one observation I would make is that current documents intermingle the explanations of how Orchard is constructed under-the-hood with how to actually use it. I think a lot of clarity could be gained by splitting the architectural stuff into the "further information" category. This relates to the "not everyone starts from the same place in MVC and DI" issue. Often the meaning of the document page is lost on the reader.

Coordinator
Oct 25, 2012 at 7:30 AM

Yes, please send pull requests when you have modifications ready to go in.

Coordinator
Oct 25, 2012 at 7:30 AM

Yes, please send pull requests when you have modifications ready to go in.

Dec 6, 2012 at 5:09 AM

Just trying to use Orchard for the first time.

The "getting started" links and the Pluralsight video immediately create a problem: Nearly all the screenshots show the "Edit" link and it's an hour or more testing (is it my log-in, are my permissions right) then searching (seeing others with the problem but not pointing to the solution) before finding where to make these edit links visible (buried under "Modules") : and all this just to be able to follow through the opening Pluralsight video.

This is just a plea for the "first impressions" links to just work. After a while sure you can count on forums, but you should not need forums for the opening videos and links.

Now back to forums to solve the next mystery of why the default home page does not show up under "Manage Content"...

Coordinator
Dec 7, 2012 at 2:24 AM

I guess you could ask PluralSight to add a subtitle to their video indicating how to enable the feature.

What's "Manage Content"?

Dec 7, 2012 at 3:39 AM

Sorry, "Manage Content" is just the heading on the page when you click Manage in the dashboard.

It shows a list of Content Items, but the "home" page (when using the blog recipe) is not one of them, so until you create a new page there's nothing in the list. And without the edit button, there's no obvious way to edit that opening default home page (of the blog recipe) when you're first clicking around.

The first link in WebMatrix is to Getting Started. There's a message there before the screenshots (that all have edit links), that says: "Since Orchard 1.5 the contextual Edit links are available if you enable the features named Content Control Wrapper and Widget Control Wrapper." But, even if you don't skip over these unfamiliar words for which you see no significance at the time, it does not tell you how to enable them (you need to find those options under "Modules" in the dashboard).

The second link in WebMatrix under "getting started" is the Pluralsight video which starts editing the default home page by using the edit link. I've started with a "blog" recipe rather than the "default" recipe, so in trying to follow the video, but without the edit links, I'm looking under Content and there's nothing there. When I finally got the edit links turned on, there's still nothing there. OK, so it's because I've tried "blog" rather than the video's "default", and blog apparently means there's no home page to see under Content. That distinction between a home page and a home blog entry though is pretty subtle! What you see as the home page in the video (with a bloc of text above the three "Leader Aside" blocks), looks awfully like what I see as a blog home page. (Maybe the blog recipe needs a simple started page created for it as well).

Anyway, my original point in the context of "better documentation" is just that it's especialy important that those opening "getting started" instructions work as expected.

Coordinator
Dec 7, 2012 at 7:32 AM

Where do you see "Manage" on the dashboard? What's a home blog entry? I'm quite confused by this. Is anybody else not seeing the home page in the list of contents?

Dec 7, 2012 at 11:01 AM

Reading Orchard documentation, which could be worse :), as a non English and a novice user, I am frequently stopped by terms that are considered as expediencies but are totally dark for me: slug, POM, etc.

Is there a glossary somewhere ?

Dec 7, 2012 at 2:12 PM

I recently submitted (via GitHub) a rewrite of the Getting Started documentation that might be helpful.  I went step by step using the v1.6 release of Orchard and took screen shots along the way.  The released documentation differs quite a bit from what a user currently experiences and this is what leads to confusion. 

Coordinator
Dec 8, 2012 at 11:17 PM

Can you point me to your pull request? I can't see it.

Dec 8, 2012 at 11:38 PM
Edited Dec 10, 2012 at 2:11 PM
I am using the windows version of github and I did a sync, but clearly I need to do something else. I am new to github - I'll take a look at it tomorrow.
Coordinator
Dec 9, 2012 at 8:02 AM

Yes, you need to push, and to make an actual pull request.

Dec 10, 2012 at 2:12 PM

I did a pull request yesterday.  Let me know if you can see it.