10/16/2012 meeting notes

Topics: Announcements
Coordinator
Oct 16, 2012 at 9:26 PM
New steering committee:
  • Sébastien Ros (59)
  • Bertrand Le Roy (50)
  • Sipke Schoorstra (49)
  • Ylan Kunstler (48)
  • Piotr Szmyd (37)
Benevolent Dictator is still Bertrand
Results and voting record can be found here (including anonymous votes):
Triage: 9 active for 1.6; 18 proposed; 16 after triage. Bar is now very high.
RC on Monday
Zoltan demo 1: Combinator now has sprite image generation
Zoltan + Benedek demo 2: scripting Orchard using PHP. You can create actions in PHP. Should be modified to use the existing scripting infrastructure (that layer rules use today). They even have a PHP view engine.
Sipke demo 1: Direct access to content types, organized by stereotype, on the admin menu.
For 1.7, let's have a work group on reorganizing the admin menu, including permissions.
Sipke demo 2: content part descriptions
Sébastien is suggesting a more pluggable setup, where modules can contribute wizard steps. Like a configurable recipe.
We need to talk about the future of the gallery.
Developer
Oct 16, 2012 at 9:41 PM

Additional notes on pluggable setup:

Perhaps allow for executing recipes and or wizards on existing Orchard instances that have already been setup.

Example wizards:
See Web Platform Installer, sets up a site step by step
See Azure Portal, it has a step-by-step setup for creating a new site

Oct 17, 2012 at 1:36 AM

Awesome news. Thanks guys!

Oct 17, 2012 at 8:05 AM

Great community and steering committee :)

May I also suggest reviewing the documentation.
New to Orchard I discover lot of obsolete articles (especially on the install and upgrade process). I have not found any version indicator (as seen in MS tech doc).

This is a clear show stopper for adoption....or some paradigm adopted based on 'only the best would survive ?'

Regards

CS

Developer
Oct 17, 2012 at 9:45 AM

The documentation is on GitHub : https://github.com/OrchardCMS/OrchardDoc

You can make changes and send pull requests and Bertrand will take them in account.

 

I also forked the repository to translate it in French : https://github.com/agriffard/OrchardDoc

I still need to translate some pages and publish them on : http://docs.orchardproject.fr/

If you are interested to contribute, I can even add you as collaborator on this repository.

Oct 17, 2012 at 11:12 AM

Congratulations to the new committee, I'm sure great new things will come forth :)

Developer
Oct 17, 2012 at 11:44 AM

Meeting video is on YouTube!

Oct 17, 2012 at 1:49 PM

@agriffard My problem is to understand Orchard and before being able to understand if documentation is Ok, I am not the best person to do this....
Concerning french translation, I don't see any necessity to do this, we all work in english. Translating product UI is necessary but documentation may not be the most urgent task, and prone to many problems ? 
I certainly want to contribute but my order of priority is code. Cordialement. CS

Oct 17, 2012 at 1:54 PM

i agree

Oct 17, 2012 at 3:34 PM

watching the meeting, one other use case for wizard steps would be configuring custom form fields and their rules

use case: recipe has a contact form, whilst setting up the site define the fields for it and what rule(s) to setup for it, send by email, store submission, etc.

I know this is probably far long into the future, but I hereby volunteer to contribute to this sub-project if needed

Coordinator
Oct 17, 2012 at 4:27 PM

@csadnt: please feel free to patch the documentation on GitHub when you find obsolete information. It's open-source too! Even just marking information as obsolete helps, you don't necessarily have to fix it (although if you can, by all means please do).

Oct 17, 2012 at 4:41 PM

Ok, I will do my best. :)

Oct 17, 2012 at 7:20 PM

I would add my voice to csadnt says.

Documentation is really the weak point of Orchard ... I understand it may not be the most exciting task but trying to find its way out through orchard documentation is really not exciting either.

Indeed many obsolete articles.

Some half obsoletes without any indication that the approach explained is not recommended any more.

No reference documentation: I was looking for information about standard Parts (Admin Menu, Menu, Navigation, ...) without any success. While going through building a web site using Orchard you'll just have to deal with tens of settings for which you can't find any reference material.

The way documentation articles are categorized don't help much. There is no progression path. We are left picking up randomly one article here and there and see if if brings anything ...

Hopefully you won't feel too bad about my comments but one has to say it loud: "Orchard documentation is horrible" :)

Coordinator
Oct 17, 2012 at 9:47 PM

Great, go for it, fix it.

Oct 17, 2012 at 10:26 PM
bertrandleroy wrote:

Great, go for it, fix it.

And how am I suppose to learn Orchard before I am able to fix the documentation? For instance, how am I supposed to get what the "Admin Menu" part does before documenting it?  

Moreover, I certainly don't have the time and the necessary skills to fix the documentation. Which is not a good reason for not saying the truth.

Now you decide but if was part of the committee, I would consider investing some efforts in the documentation. IMO, the supposed Orchard "steep learning curve" that I can read here and there is mostly due to the documentation. And I'm sure, the only reason you don't have more complaints and frustrated feedback is that people are afraid (or shy) of looking silly. I'm not (but the reason could be I am) :)

Can't you get the help of technical documentation specialist within MS?

Developer
Oct 17, 2012 at 10:34 PM

I think the code is quite well documented without the need for documentation. Quite often I just read the tests to understand what to do. If I get stuck I look on the forums... Else I bug Bertrand (Sorry Bertrand)

The documentation takes a lot of time and effort. Its a toss up between adding features and fixing bugs to adding documentation. As Developer we hate writing documentation, not because we aren't good at it, but because we would rather write code. What I am trying to get at is if we chose to write documentation all the time people would complain about not adding features or fixing bugs.

I would argue that Low level documentation these days is an unnecessary overhead to a project, and that the things that should be covered are the high level concepts which are already covered for the most part.

Coordinator
Oct 17, 2012 at 10:53 PM

> how am I suppose to learn Orchard before I am able to fix the documentation?

By looking at the code, like everybody before you did.

> I certainly don't have the time

Neither do I, sorry.

> if was part of the committee, I would consider investing some efforts in the documentation.

In order to invest, you need resources. In an open source project, resources are users. That's you.

> Can't you get the help of technical documentation specialist within MS?

No.

Oct 18, 2012 at 12:28 AM
bertrandleroy wrote:

> how am I suppose to learn Orchard before I am able to fix the documentation?

By looking at the code, like everybody before you did.

> I certainly don't have the time

Neither do I, sorry.

> if was part of the committee, I would consider investing some efforts in the documentation.

In order to invest, you need resources. In an open source project, resources are users. That's you.

> Can't you get the help of technical documentation specialist within MS?

No.

So basically, I should go through the documentation just in case... and if I can't find anything, I go through the code? Great workflow ... 

Handling an "open source" library for developers and a CMS is not exactly the same thing. In order to get resources investing time in documentation - "users/us/you" - it is expected that the committee acknowledge the importance of the documentation instead of being told by its members to do it ourselves if we do not like the way it is...

Never mind ... Orchard is certainly not for me...

Coordinator
Oct 18, 2012 at 12:44 AM

An open source platform that expects its users to contribute is probably not for you, no. Who said we do not acknowledge the importance of documentation? Certainly not me.

Oct 18, 2012 at 1:43 AM
bertrandleroy wrote:

An open source platform that expects its users to contribute is probably not for you, no. Who said we do not acknowledge the importance of documentation? Certainly not me.

The fact that I took the time to spend a few days reading the documentation, creating a test site for going through the parts, content types, queries, projections, etc... and that I provided feedback to confirm that the documentation is really bad/confusing and, as told by someone else, can be a real show stopper IS a *contribution*.

Even if you didn't say that you do not acknowledge the importance of documentation, it can be clearly noticed that as soon as someone (csadnt) suggested to review the documentation he was told, where he could find the documentation, and how he could change it, and so on ... Not even a word saying that this was indeed a concern, that maybe you were focusing on some major features before going into a rework or maybe that you just don't see what is wrong... 

You are way too touchy when someone seems to question something ...

Coordinator
Oct 18, 2012 at 2:11 AM

Thanks for your contribution then. Documentation is of course a concern, as are the bugs that we need to fix, and the missing features that we need to implement. You won't see us spending much time acknowledging those either, but it doesn't mean that we don't care or that we aren't doing anything. We've had some valuable contributions lately to documentation, which shows that it's not an impossible or unreasonable thing to ask the community to contribute. It's not just a matter of having the steering committee decree that there shall be documentation for it to magically happen. Again, the resources we have are the community. Thanks for suggesting asking Microsoft to contribute, but we had thought of that already, and they did contribute a lot of documentation in the past, but this is unfortunately out of the question currently. They already contribute a full-time developer (and what a developer) and server resources, and they have other priorities they need to address.

I wish I could give a better answer, or one that would be more satisfying to you, but the truth of the matter is that the first answer you'll get to "I want X" is almost always going to be "great idea, make it happen". Welcome to open source.

Oct 18, 2012 at 12:58 PM
You are way too touchy when someone seems to question something ...

@FredericLatour Well, you may feel that way, but that's life on fora sometimes. Short straight answers do not always sound nice, but don't take that personal.
Sure, you're right about the documentation. You're not the first to mention that.
Maybe we need a 'Writing documentation' topic where anyone can start a discussion to improve the docs.

Missing documentation is one thing, but wrong documentation is worse. It might be an idea (for some of the gurus) to go through the docs and mark sections that are not 'up to date' anymore. That way, it takes the least amount of time for the gurus and new readers are aware of modifications and it also gives doc writers a chance to improve where necessary.

If you're stuck with Orchard, please start a discussion and share your story. Most probably, you will be helped.

Coordinator
Oct 18, 2012 at 5:51 PM

Yep, the topic was started yesterday. Please join in. http://t.co/Em11W2Ez