Recompile documentation for Rules

Yep, we definitely need to improve the docs. First off, we should probably make sure we have the same docs as in d6 for rules2 too.

>http://drupal.org/node/298476

me and klausi thought off going through the doc pages and making sure they cover both d6 and d7, and maybe to point out the differences. Or would you suggest to split everything up into separate chapters like the developer docs?

+1. I know it's just a matter of time, but there is very little 7.x documentation (specifically vid tutorials) out there. At this point I'm kind of lost. I can understand the idea, but not having any luck getting around the ui and executing on my end.

Looks like Itangalo has done a lot of work lately. Could you please go through it and update this issue?

fago --

You have a great module. And I think, hands down the worse developer documentation for any other drupal module that is as important.

Looking through modules that attempt to integrate with Rules 2.x, very little of your new stuff is getting use. Even the videos from the folks in Sweden use only the simplest, most trivial parts of the API.

At a minimum, *please* start adding sample code that uses real examples. The test code shows the APIs, but after spending hours on your docs, I have not the slightest idea *why* anyone would call these things.

It would help if the docs concentrate less on the the how ("read the Entity API documentation") than on the *what* developers need to do, such as:

• How to write an event that integrates with a non-trivial action like sending mail.
• How to write a call back, using a complete example with code that's not put down with no context (i.e., what function is the code put in, how is the code called, etc.)
• How to do a form-based configuration interface for rules. The default UI is so technical that I still have no idea why I'd choose to do things that way. Or what would happen when I chose them.

Without better sample code, you are not going to get most of your new stuff used. I'm still looking for modules that use Rules 2.x APIs, and I'm surprised how little these modules do. The rules_example module does not cover much of anything from the new API. Please help them out by adding examples that are concrete and useful (rather than abstract and full of "foo" and "bar" and such frack).

This seems like a good module, I would love to use it, but guess what, I cant figure out rules 2! Good tutorials mostly exist for rule 1 and seems like there is good difference with these two when it comes to UX and Terminology making it hard to follow the examples in rule 1. I spent a couple of days trying to figuring it out, and I am still no farther down the path than where I started. Almost like chasing the end of the rainbow for the pot of gold! There is hope but wont get there anytime soon.

http://dev.nodeone.se/en/learn-the-rules-framework is pretty useful for getting started with Rules 2. Check it out.

Rules 1.x Handbook became the Rules 2.x Handbook (crufting), then Itangalo's screencasts were broadcasted but still a little hard to find (fragmenting), and then came lots more questions in the issue queues and g.d.o/rules (down-pouring)....

We've had some growing pains, but look how much content we have about rules!!! Now...
Let's compartmentalize and centralize all the content!

And, in addition to working on the documentation, let's also #1498854: [Meta] Refocus discussion group to announcements and development because that could be another great resource.

tag

another tag

The content in http://denver2012.drupal.org/content/rules-mastery looks like the most complete single resource. This content should be worked into whatever location we use as the starting point for directing people to Rules' Docs.

I modified the docs a lot to address these issues.

On a related note: Itangalo, magnificant job on skill compass! I love this resource and can't wait to see it on drupal.org/rtfm :-)

good site builder documentation

I tried to make it easier for site builders to find the information we care about. The concepts are easier to get to, but there's still good amount of room for improvement. You may also want to check out skill compass. http://skillcompass.org/topic/rules

I also would love to see (do) some relevant benchmarking on the rules

Here's a good node to put that on: Performance Considerations

I want to help with this issue, but need some guidance by the module maintainers and senior users how to use all the features in a meaningful way.

That's terrific. Here are some links that will give you good info from multiple perspectives:

• Helping maintainers in the issue queues
• Use the issue queue
• Creating a role for "Support Maintainers" in Drupal Contribution Modules
• Issue Summary Initiative

#4: Yes, making the relevant examples more easily accessible would be great.

Almost like chasing the end of the rainbow for the pot of gold!

worth restating.

There's still a lot of good stories here worth that would be good to make sure we address. Marking as needs review.

@Itangalo: I assigned this to you to solicit a review. Thank you very much in advance.

Hi

@mitchell: Thanks! I hope skillcompass.org can help influence (and evaluate) some improvements to docs here at drupal.org.

Concerning where to put documentation: I think that drupal.org should be the place to put docs. Right now it is difficult to maintain and find, but it should still be the place. Thus, I vote for not moving docs elsewhere.
I had plans on moving the Rules Mastery documentation to the docs on drupal.org, but I haven't yet had the chance. If anyone has the time – feel free to do it.

Thanks to everyone who posted their feedback about the handbook. Hopefully we're now much closer to meeting Rules 2 users' expectations for the docs. If you'd like to discuss this further, then reopen the issue, but IMHO, it'd be better just to edit the handbook directly and solve existing issues that are marked Documentation.

My final notes for this issue:

I did my best to give the docs more flow and relevance to D7, making important site builder topics more easily accessible and consolidating sections where possible, which should help with navigation. Taking on fago and klausi's idea to "split everything up into separate chapters like the developer docs," I setup a new layout for the content in Site Builder Documentation, which I renamed from Rules Explained. Some of the content in there could really use some love, but it should be very easy to flesh out using the structure I described and by searching for relevant support requests that you can just copy and paste from. The section Common Configurations is how I decided to include what someone once asked for, "[a list of actions available by default]", and it is where I think it makes sense to include a mini tutorial (more on tutorials below) on using those features. I believe this section will be especially helpful for everyone, but it needs more work.

The navigation is dramatically improved, but it's important to see that there is a ton of content in there (massive cred to fago, Itangalo, and many others), new links to related resources, new sections organizing them, and a number of new pages that I wrote up; so if anyone wants to help with minor clean up, consolidating content, or making large changes to better cover important topics, that would be terrific. The missing content in Site Building is especially important to flesh out.

The introductory pages are also reorganized and reworked into other parts of the docs to provide a more bookish feel. I disentangled the D6/D7 docs, which is better for D7, and the D6 docs are now in in 6. Rules 1.x / Drupal 6 (perhaps a better title is in order). I found it too difficult to navigate and organize both versions together; plus, pages are now fewer clicks away and the sidebar is a lot easier to use. I think this also alleviates the need to "go through the doc pages and making sure they cover both d6 and d7, and maybe to point out the differences," but I would appreciate it if someone went back over the D6 section to make sure nothing is left out. If it is left out, then it's most likely just in the main docs now, which even though they're mostly D7 specific (that was the goal), I think that's a decent compromise if the majority of the info is in one place and D6 specific info is in a separate section.

The Developer Documentation was already in the best shape; I just updated some links to the API docs and tried to make the Contributed Features and Examples more useful for finding good example code. There are lots more plugins in contrib that should have pages in the Contributed Features and Examples to help both site builders and developers, so please add them if you know of them. Userpoints, Voting API, Mimemail, Page Manager, and FFMpeg come to mind. The pages that currently exist, like Views, Rules Link, Forms Support, and others don't feel too organized, especially considering how valuable they are for many configurations. If we are going to focus on the Common Configurations section to cover the knowledge for ~80% of use cases, then this section is important at least for another ~15%. There are still a lot more well-developed modules with Rules integration, and these are great at illustrating the extensibility and available code for Drupal.

The scheduling section could use cleanup and consolidation, and it would be especially awesome if at the same time, whoever fixes that up incorporates and answers the ~10 existing support requests on scheduling rules.

I began a page on Data Conversions, Calculations, & Transformations to cover these new features recently commited and in development. The particular topics in that page can be discussed in the issues where the code is coming from. This is also comparable to the Lists, Loops, and Recursion section, which also has a lot of ongoing development that is not yet reflected in the handbook.

A lot of the D7 tutorials and guides were neglected (which I moved to a section for "Old resources"), and I started on moving over the descriptions of the functionality in that text into the Site Builder's feature explanations (Common Configurations). That way we can keep a canonical description of the features and not have to maintain multiple versions of what would be the same text. One or two simplified examples in each of those sections should work better imo than a bunch of repetitive tutorials, which was much more successful in D6 than in D7.

If we switch from encouraging writing new tutorials and instead focus on documenting how to use Rules' features in the specific page under Common Configurations, and then also help to curate the projects tagged [Rules, Examples, and Features Package], then both the code and the docs will be more maintainable and comprehensive. Many of the tutorials are actually obsolesced by feature packages that can also handle the specific issues faced with their specific implementations. There are still a few tutorials that could be developed as actual projects, so this should be a major focus moving forward. These projects add tremendous value to site builders looking for examples to guide their own configurations and help save time from duplicating the efforts of previously configured rules. If these configurations are more widely used, that will be a benefit in and of itself that will indirectly help documentation efforts as well.

I considered copying the gdo "Integrating modules" page into the handbook, but since most of the content is outdated and there are better ways to find the content by using the Project browsing tools, I decided to leave out that content. I also recommend that we deprecate that wiki page. The FAQ on gdo is also dated, and if we build out the Site Builder sub pages from support requests in the issue queue, then that page shouldn't even be necessary. Even starting a FAQ tag, as I did in the issue queue, seems to miss the ball, because if people have to ask, then it's because they couldn't find the answer in the docs. Most of the content from that FAQ is in the docs now, except for: The node id (nid) of some content is missing! & I've installed the latest token module, but my tokens are still not replaced. What's wrong?

If you read up to this point... wo!. You must really be interested in this project too. I hope this has been helpful and you have an easier time finding documentation that suits your needs from this, and hopefully it gave you some ideas on how to add to the handbook or contribute to Rules in other ways.

Cheers!

Just wanted to give a +1 for the great work. Cred!

> If you read up to this point... wo!. You must really be interested in this project too.
I did it! ;-)

> If we switch from encouraging writing new tutorials and instead focus on documenting how to use Rules' features in the specific page under Common Configurations, and then also help to curate the projects tagged [Rules, Examples, and Features Package], then both the code and the docs will be more maintainable and comprehensive.

Yeah. This is very true, but also very difficult. I know I have a substantial amount of docs over at http://tinyurl.com/rulesmastery that I would like to get over to drupal.org at some point, and there are of course also the videos I have over at NodeOne's learning library. And "the Tiny Book of Rules".
Do you think there's a reasonable way to get these into the canonical docs for Rules? Or should I just be happy with having them in parallel? (Having parallel documentation outside d.o is unavoidable, I think, but maybe it could and should be avoided inside d.o.)

Ok. Let's keep this going. Again a long post...

Restating the premise of this issue:
>"What I'm missing right now is a more "in depth" documentation that describes the powerful features of Rules 2 and how to use them in the site building process."
>"I want to help with this issue, but need some guidance by the module maintainers and senior users how to use all the features in a meaningful way."

Editorializing for a sec..
I just noticed an apparent logical contradiction in the second statement (teach me, so I can teach others, so that you do/did not have to teach me and/or others). For some reason I'm drawn to paradoxical, chicken-in-egg logic and life challenges, so to have a little fun and try to help with what that topic, I'll don my philosopher hat for just a moment and say a little something (from my own experience, and it may or may not serve you and others well) that I think fits. Let the work you appreciate by others inspire and uplift your own motivation; and don't wait for others to do when/what you know you're the right person for the job, even if you're not ready. Life's a process. Learn by doing.
---

Open questions:
-Is Common Configurations a clear name for documenting Rules' features?
-Is the strategy I laid out for Common Configurations a good one?
-What else should we do for this issue?
Remaining tasks:
-Remove FAQ and Integrating Modules pages. (Itangalo, can you do this? Do you agree with my reasons above?)
-Flesh out Common Configurations!!
---

>> If we switch from encouraging writing new tutorials and instead focus on documenting how to use Rules' features in the specific page under Common Configurations, and then also help to curate the projects tagged...
> This is very true, but also very difficult. I know I have a substantial amount of docs over at http://tinyurl.com/rulesmastery that I would like to get over to drupal.org at some point, and there are of course also the videos I have over at NodeOne's learning library. And "the Tiny Book of Rules".
No, no, I was referring specifically to migrating the section in the handbook for tutorials, the main issue being that each tutorial is likely to describe the action its using in some way rather than referencing a canonical description. This also applies to books, videos, and training materials but that's inevitable in those resources.

I just started to implement that approach by reorganizing a lot of the content from that section into Site Building as well as the Support Request issues, so it's still a bit speculative of the benefits, but I really believe this is a sound approach. In regard to the mentioned resources:

Tiny Book of Rules
I already copied over the intro paragraphs to make the cover page a lot more informative and inviting. The other subsections in Site Building should be useful for improving a number of pages in the handbook, and the IA I started for it will hopefully make it easier to enter, organize, and manage this content in a primary location. Tiny Book of Rules and Site Building Essentials will still remain relevant because they serve a different need, ie printed, portable, and offline resources.

Rules Mastery
This is unique, because exercises aren't reference materials. While I haven't personally gone through all of it, AFAICT it is a set of tutorials with accompanying code and videos. My perspective codes published outside d.o, in wiki pages, pdfs, pastebins, and videos is that it's not appropriate for long-term use. Upstream changes are significantly detrimental to their long term viability, and there is usually little or no tools for others to help maintain and continue to develop them. Putting them in projects is the best approach I can think of (probably not worth prioritizing atm). Perhaps the Docs Team has discussed plans to incorporate training materials on d.o, but I haven't looked into that or thought about this myself. Are you familiar with any discussions or have any unpublished thoughts on the matter?

NodeOne's Learning Library
Both of us have already copied over some of the video descriptions to fill in gaping holes in the scheduler and other features. That has worked well, and most of that text just needs reformatting and simple edits to fit a handbook's style. Videos have always been done in parallel, because drupal.org/videos used to be a very unmanageable resource; #302106: Video training subsite for d.o is where I hope to address this with an appropriate, realistic, and awesome solution.

> Do you think there's a reasonable way to get these into the canonical docs for Rules?
Yea, we can't put everything in the docs; that's a cumbersome strategy. On top of that, I doubt anybody actually likes using the book.module, but I'm hopeful that as we #1549580: Track progress of building the Help/Docs System and complete that initiative, this process will be a lot easier in the future. I think, at a minimum, we should provide a clear, navigable set of content that cover all the major functionalities of the project inside the handbook, ie a training manual. Beyond that, I agree there will be other external resources that go as deep into subjects as the author wishes to explore, ie fago's master's thesis or your two ~20 part video series :-).

I think, in general, if we work on the docs as features are developed (like core), then creating resources book and video resources will be much simpler, mainly repackaging that content for those who prefer that format and updating it to reflect major changes in the future. That'll be something to consider moving forward, and in the meantime, we have some work to do to that will complete a fundamental aspect of a fundamental Drupal module, so I couldn't be happier about the state of Rules.

The docs need to be updated proactively. When a solution to a configuration question is confirmed or a change is made to the code base, the docs need to updated to reflect this. These measure will assure that the same topics won't have to be addressed over again nor users' time wasted rethinking and researching for "the solution".

IMO, the issue queue has exploded to serve the demand for this information when it hasn't been available in the handbook. That's a major premise of this issue, and to solve it, we'll need more volunteers to handle both the existing and oncoming issues. Leaving valuable information in the issue queue is terribly inefficient; it's unwise to expect people to rediscover information. The difference between accepting and rejecting this approach, by my estimation on the multiplying gains and losses in an upfront versus delayed cost/benefit, is exponential versus linear growth in Rules understanding and capability.

I believe this is the only viable solution to fix complaints about Rules being powerful but incredibly difficult to get figure out how to accomplish common goals. If we are to set a policy in the issue queue, how should responsibility be distributed between the questioner, the answerer, and other volunteers? Let's put this in the Rules issue queue guidelines and create another issue for "Documenting X Guidelines" if need be.

Another todo using Views in Rules w/ VBO

• Make Rules dance with Views Bulk Operations (D7)
• VBO's docs
• #596552: Improve usability of Rules' Queue API integration is also related.

These pages should be helpful to those who want to help:

• Creating pages in the Drupal.org online Community documentation
• Documentation maintenance tasks

Re: #16: Let's focus on documentation guidelines in another issue.
Does anyone know where the Drupal Core documentation guidelines can be found?

This issue has been idle for almost 10 years. At this point everything it discusses is quite outdated.

Rules will always need help in building and improving the documentation. A lot has been done in the past 10 years, and a lot still needs to be done. I don't think keeping this issue open and idle is helping.

If there are specific things that need to be done, then please open specific issues. Also, Drupal is open source, so anyone can write their own documentation at any time and post it on drupal.org - it does not take an issue or a community initiative to contribute documentation or patches for missing or inaccurate documentation.