explaining modules

Topics: Administration, Announcements, General, Writing modules, Writing themes
Nov 17, 2011 at 11:54 AM
Edited Nov 21, 2011 at 9:10 AM

I think that every developer that create a new module have to explain how it can be used! He has to write which parts are installed with that modules, which widgets, what change in the admin menu....         I think that these features are very important to everyone who would install the module!

thanks developers for your works!

Nov 27, 2011 at 2:17 AM

I agree with this. Almost every module in the Gallery has NO Documentation whatsoever. I've never seen this in any major CMS community. Are we suppose to just guess how they work? Especially when it's not obvious. Module developers need to submit documentation on how their modules work.

Developer
Nov 27, 2011 at 10:49 AM

I agree, documentation is very important, that's why I struggle to provide some documentation even for my trivial modules. However please understand that writing documentation is also (non-negligible) work. Help developers by reporting bugs or confusing functionality and by asking them questions before dropping the module, so they can produce quality modules and write better documentation about necessary topics.

Nov 27, 2011 at 12:38 PM
Edited Nov 27, 2011 at 12:39 PM

I agree with all the statements above!

I just installed this asp.net/orchard software on Thanksgiving and I still get lost with some of the modules I have tried, I would surely agree  with better documentation on how to install/use. Laughing I'm still trying to figure out how to delete a module that I decided not to use after I disabled it.

All in all though after trying between 14 and 18 other asp.net packages my hat is off to the developers, I have been looking for months to replace my php wordpre** site with a asp.net site and this package has the look and ease of use just like my php site.

Thanks guys I look forward to all the releases in the future.

 

 

Nov 27, 2011 at 1:23 PM

Piedone makes a very good point, writing documentation is no piece of cake. I've tried to document the important functions of my modules but it's extremely time-consuming to write concise, clear docs; and this is all stuff I do on my own time and for no financial gain!

Of course, these are all free and open source community projects, and anyone with time on their hands who would like to help out are welcome to contribute to the documentation effort themselves. Especially if you are using Orchard and these community modules to make money from your websites, it's a very simple and effective way you could consider to give something back ;)

Nov 27, 2011 at 1:44 PM

Hello randompete

I agree with you, in the past being in the auto engineering field I had to write reports all the time and they had to be very detailed and to the point. but for me to write on or about a module would be way over my head being I'm just your normal noob with not only Orchard but also asp.net. My hat is off to you and all the other community contributers.

Again as stated if you look at some of asp.net and php blog or cms open source software sites most if not all the time some kind of install docs are included if not for anything else to help the noob if not the advanced user or developer. I hope in the future that more free and pay for modules will come online. And yes I agree free is free but if I don't know how to fully use it why even does a developer post it other then another developer can pick the code apart and findout how to use it.

And let me state I have paid for module in the past. But no matter what,  I do enjoy trying to get great looking modules like yours to work.

 

 

Nov 28, 2011 at 8:40 PM

Thanks, I appreciate your comments. At the moment Orchard and its surrounding community are still relatively young, although it is now becoming increasingly mature; in another version or two it'll have some seriously overpowered features to rival the best CMS's out there (and in my opinion it already wins outright in a number of key areas). So at this time most module developers are still learning, and keeping up with new changes and features. I'd rather someone just pushes a module up there if I (or anyone else!) might find it useful, than feeling they have to wait until everything is properly documented, which they might never quite find time to. I've been really enjoying sharing and getting inspiration and learning new things from other developers' code.

The thing is, most modules are actually very simple and don't really need a huge amount of documentation. I'm happy to see simple step-by-step instructions, which most modules I've used have provided at a very minimum. Even without that, all modules install through the same very simple interface, it's covered in the Orchard docs so I don't see that each and every developer has to also go through the same tutorial. And what most modules will give you anyway is a new Content Part to attach to your Content Types, which again is all done through the same, consistent interface, and with some experimentation it's usually fairly obvious what they do. There are very few modules that actually expose anything complex like a public API which you might need documentation for, and in those cases it can't actually hurt to have to look through other people's code (trust me, I have learned huge amounts this way). Finally, you can always ask around on discussion forums or message project owners to get detailed help.

I'm not saying that module authors shouldn't try to eventually make their product a shiny, polished piece of work complete with instructions, tutorials, screencasts, example projects, and so on; but really I think the status quo isn't so bad as the OP implies, and a lot of modules are still works-in-progress anyway. As Piedone has said, you can help just by the simple thing of letting developers know exactly what you found hard or confusing, so they at least know what to improve on. Well, we have two things already from this discussion - it might be a good idea to at least link to Orchard's documentation on module installation; and as the OP suggested just providing a basic list of features, parts, widgets, and menu options is a really good start. Personally, I've admitted on numerous occasions my own documentation could be a lot better!

Anyway, a big thanks to all the module community for helping make Orchard better and better, and of course to all users of Orchard - after all when I release these modules, I of course want people to use them :)

Nov 28, 2011 at 8:52 PM
Edited Nov 28, 2011 at 8:54 PM

I agree with all the statements above And a big thank you for the Module Developers for their work so far. And when I speak of documentation, I'm not asking for a 300 page Manual on how the module works. But maybe just a 3 step process on how to get it started. I install modules all the time and can never even find them in Admin UI. No idea what to do with them or even how to start using them. Perfect example is the Forms module made by the Orchard team. I installed this and can't find it anywhere in my Admin? Is it a content item? a content part? Is it a class library or API? What are the classes? How do you use it ? I click on the Project site link and it sends me to the Orchard Home page.

Again just a simple 3 step process to get the module started.

If the module is  intuitive enough that might be all someone needs.

 

Oceantrain

 

p.s. A 2 minute youtube screencast on how to get a module up and running would be great as well.

Nov 28, 2011 at 11:25 PM

Documentation is definitely needed for the new Orchard features, although Bertrand has written quite a bit on his blog, and of course there are existing examples in other Orchard modules.

Forms is just an API, it doesn't give you any new features unless you're a module developer. The various bits of UI you see in the Rules module, however, are mostly built using Forms, so you can see it in action (and it's pretty easy to work out how to use when you look at the code).

Anyway, this discussion has given me a new idea: a Module Help API. Basically a system allowing developers to package documentation along with their module which would surface links to help with appropriate UI hooks ... e.g. on the module / features lists, in content item editors, on the parts list, etc. Do people think this sounds like a worthwhile project?

Coordinator
Nov 28, 2011 at 11:26 PM

Sure.

Coordinator
Nov 28, 2011 at 11:29 PM

YAOM ...

Nov 29, 2011 at 8:15 AM

Hello randompete

I agree with you on Orchard after trying maybe 12 other packages I found Orchard to fit the bill for something I felt had easy of use but functions and I was looking for also.

I can't wait to see more of the modules and updates that come out of this great product.

Thanks again.

linuxhavok