There doesn't seem to be any community documentation available for the Group module. So I've just started a brand new Community Documentation page, with some minimal content (nothing new/spectacular for now, just starting ...), and pretty close to OG's community docu (right in front of it ...). If the location within the book hierarchy is not the right spot, feel free to move it to wherever it fits.

I recommend to add a link to this new docu page on the project home page. Anybody interested in contributing, please go ahead to do so over there ...

Here are some topics (child pages) that I suggest to be included in these pages:

  1. Why should one use this module?
  2. Getting started (installation / configuration).
  3. Related modules.
  4. How to contribute.

This issue will be used for now to track enhancements to this kind of documentation (PLEASE do not use it to post comments that are not about tracking such enhancements).

For what it's worth: I've contributed (quite a bit) to similar community documentation for other modules like these:

  1. Chart.
  2. Charts.
  3. Forena Reports.
  4. Visitors.

Everybody has their own (documentation) style of course. But if I'm to decide, I'd recommend to use a similar set of child pages (structure) for the Group module also.

Of course, if there is any existing community documentation hanging out somewhere, please let me know via this issue (so that we can find out how to best integrate / reuse that somewhere, similar to what I did for some of the above mentioned modules in the past).

And yes I'm aware that work is going on for D8, but "this issue" is about the D7 version (first things first, anybody interested in a similar D8 issue: go ahead and create a similar issue).

Comments

Pierre.Vriens created an issue. See original summary.

kristiaanvandeneynde’s picture

kristiaanvandeneynde
Primary language Dutch
Location Antwerp, Belgium
CreditAttribution: kristiaanvandeneynde at Deeson commented

Thanks Pierre, I really appreciate the effort you're willing to put into documenting Group. If you need any information or feel uncertain about something, feel free to ask me any questions.

I like the documentation style you've put forward in the summary so I reckon it's a good idea to start off with a similar structure. If you want me to review the documentation and its overall structure as grows, give me a shout as well.

P.S.: If you're mentioning George from DC Amsterdam '14, it may help to explain what that means. I was at the Driesnote myself and had already forgotten about him, I must admit. Alternatively, you could rephrase it to state the idea behind George instead of referring to George himself.

Pierre.Vriens’s picture

Pierre.Vriens CreditAttribution: Pierre.Vriens at In Petto commented

Merci Kristiaan for your "go"! And offer to assist where needed.

About "George": who am I to summarize what Dries was explaining then? I doubt Dries will step in in this issue to do so (again), but this is what I remember from (or at least how I interpreted it). It was about "the tragedy of the commons" ... a nice public park in Boston that many people like, take advantage of, etc. But what does it take to keep such park nice (clean, etc)? Something like a gardener (for the flowers, the grass, etc). So how do you make sure that also happens? Either you make them happen buy funding somebody to do so (via taxes that are used for it) ... or you just "wait for George to do it (for free ...)". But what happens to the park if George doesn't do it either? It'll be tough to blame George for not doing it, right?

Anyway, this is just "my" recap of it. Hope I succeeded ...

PS: yesterday I found an interesting "answer" at http://drupal.stackexchange.com/questions/108064/how-to-implement-an-opt... ... expect a link to it in the community docu soon!

Pierre.Vriens’s picture

Pierre.Vriens CreditAttribution: Pierre.Vriens at In Petto commented

Kristiaan, what are your thoughts about my "I recommend to add a link to this new docu page on the project home page"? Actually there is a specific field for that on the project page that will be used as the "Read documentation" link (if you enter some hyperlink in it). Do you want me to create a separate issue for that, or is it sufficient the way I included that here? Also, what about the timing to add such link? FYI: If you agree to add such link, I recommend to add it "the sooner the better". So that people already know there is "something" (I searched quite a bit before I started this issue to discover there wasn't anything yet), and maybe also to inform people where to best produce (store) "other contributions to that docu".

kristiaanvandeneynde’s picture

kristiaanvandeneynde
Primary language Dutch
Location Antwerp, Belgium
CreditAttribution: kristiaanvandeneynde at Deeson commented

I'll put the link in the documentation section of the project page as soon as there is a bit more info.

I agree that it should be there as soon as possible, but right now we'd just be redirecting people to a single page with little more info than the actual project page. From a UX point of view that doesn't feel right.

unqunq’s picture

unqunq CreditAttribution: unqunq commented

I'd like to help with this because I am currently trying to learn how to use it.

I enabled the main module and expected to be able to do a lot of things that were demoed in a recent talk. However there are some extra modules that need enabled if we need extra functionality:

  • Group Node
  • Group User
  • Group Invite
  • Group Add
  • and more

After a bit of configuration all worked fine.

Pierre.Vriens’s picture

Pierre.Vriens CreditAttribution: Pierre.Vriens at In Petto commented

@unqunq : merci (oeps thank you) Nick! Looks like we're in the same boat ... I'm learning about it to. Can you edit your prior post a bit please with some details about:

  • The kind of questions you ask yourself (for which you'd hope to find some docu about it)?
  • Do you know of any interesting articles, posts, videos, etc anywhere on the web?
  • Are you interested in digesting the existing issue queue, to locate all sorts of hidden docu in any of the (closed?) issues? If so, please add a parent link in such issues to this one here (to make it a child issue), or a "related" issue.

FYI: I'm planning to soon create more "child pages" of the community docu I started, to further complete the "structure" (pages and sections) of what I have in mind.

PS: I keep hoping that Kristiaan will soon add the link in the "Read the documentation" link on the project homepage (I keep struggling to find the community page again whenever I have time to continue on it) ...

kristiaanvandeneynde’s picture

kristiaanvandeneynde
Primary language Dutch
Location Antwerp, Belgium
CreditAttribution: kristiaanvandeneynde at Deeson commented

Hi guys, the link that Pierre is currently working on is https://www.drupal.org/node/2666972.

Once you feel like there's enough info there to answer the most basic questions people may have, set this issue to needs review and I'll have a look.

Cheers!

izmeez’s picture

izmeez CreditAttribution: izmeez commented

Thanks for starting the docs. Having used organic groups extensively I have been curiously watching the emergence of the group module. Further stimulated by the recent post, https://www.deeson.co.uk/labs/9-reasons-group-drupal-8-awesome

Rustan’s picture

Rustan CreditAttribution: Rustan commented
Status: Active » Needs review

I made some small additions, most notable a basic setup walthrough, and I think it is now useful to link to the documentation from the module page.

Pierre.Vriens’s picture

Pierre.Vriens CreditAttribution: Pierre.Vriens at In Petto commented

@Rustan, merci beaucoup for stepping in for the docu stuff. I saw your walkthrough you added, helpfull, but I have 2 "comments" about it, which I'm posting "here" to avoid cluttering the docu pages with comments below it:

  • if you did not first create a group type, you cannot create a group. So I think something is missing, or in the wrong order, near step 3 (= crete a group)
  • getting started with the Group module, also implies that you have to understand/figure out what the exact usage is of each of the submodules like gnode, ggroup, etc. Therefor I suggest we use 1 subpage for each of the submodules, and only withint those submodule docu page we add something like "enable submodule xyz". If you agree, I'd remove the "Activate submodules as you need them" from step 1.

Extra question/request maybe for Kristiaan (to answer): as of today, I'm still trying to figure out (via trial and error), what exactly each of the submodules is supposed to do (used for). So far I've only found like a 1 phrase explanation of each sub-module, which to be honest does not really mean a lot to me. If you can, would you mind adding like a few phrases / paragraphs to explain each submodule's usage on the main community docu page. If you can, can you also explain what the functionality is that you get if you do not enable any of the Group's submodules? I have the impression that not enabling any submodule does not make any sense (you need at least 1 submodule), so it would be nice if you could explain something related to that also. I bet these are stupid, really getting started questions. But that doesn't mean they should not be documented (because I bet I'm not the only one asking such questions). And somebody who cannot, or does not want, to read the source, should be able to also get an answer to such questions.

Last but not least: as per @Rustan's "... link to the documentation from the module page...." we now have 2 votes/requests to do so. Please don't make the mistake of never "releasing" something. There is always room for improvement, and it will never be perfect and complete. Every time I want to continue working on community docu, I have to (a) find the group module (b) find its issue queue (c) find this issue (d) locate the community page link (e) find the childpage of that link. And this on the various devices I use. That's not really motivating to just get started on "contributing group docu on D.O" ...

Rustan’s picture

Rustan CreditAttribution: Rustan commented

Getting started page was empty, and I thought about what could fit in there :)

Oops, I missed create type. I fixed that and restructured a bit.

I disagree, not activating any submodules on your first setup has no automatic value, like activating only the base module and not UI submodule for views has little meaning...

The big green button takes a lot of space, are they recommended to use? Seems like showing the need for more help should be auto-generated by the system depending on the completeness level of the documentation page.

Subpages per module already exist (I added the missing ones), I changed the links from the front to point to them instead of directly to code. Code link is on the sub-page. I think the one-sentence description on the module page and on the front of the documentation is fine, more details can be added on the sub-pages.

Why did you note the strict difference between a howto and a tutorial? The length of the document depends more on what you want to do, and a list of topic titles makes it easy to navigate. At least until there are 30+ posts :) Or do you mean that beginner tutorials should be under getting started?

The links to the issue queue are not that helpful. Searching the issue queue will lead you more directly to the relevant issues. Also the links to Stack Exchange mostly seem to link to OG issues. This is confusing. I cleaned up and added the most useful of the links as howtos. I suggest removing all the links there, and shortening the description to just about "here are howtos".

kristiaanvandeneynde’s picture

kristiaanvandeneynde
Primary language Dutch
Location Antwerp, Belgium
CreditAttribution: kristiaanvandeneynde at Deeson commented

Okay I've taken a look at the pages and I agree we should link to them rather sooner than later. However, in order to do so there are a few things I'd like to see changed:

Separation

At the top level create two subdivisions: "Group version 8.x-1.x" and "Group version 7.x-1.x", this allows us to separate the documentation by version. Should I ever decide to backport 8.x-1.0 as 7.x-2.0 then we have room to document that version.

Clean pages

Get rid of the green buttons please. A documentation can be tagged as incomplete in the top right corner. Having call-to-actions all over the place will just break the page flow and perhaps even push people away as it makes the documentation seem lacking.

Canonical documentation (Can be improved while we already link to it)

We should keep the documentation in one place. Linking from the project page to a documentation page only to be linked back to the project's issue queue, telling people to read through an entire issue is just bad UX. We should have a clear explanation of something in the documentation and perhaps link to the issue that has more detail at the bottom of the page. Although I'm still convinced we should just not link to any issue.

Clear overview (Can be improved while we already link to it)

We should have a user friendly index covering the most sought after topics, such as (just an example):

  • Module purpose
  • Common use cases
  • Getting started
    • Setting up a group type
    • Creating your first group
    • Configuring group permissions and roles
    • ...
  • Module integrations (submodules and contrib extensions)
  • Developing for Group
  • ...

Also, I'm a big fan of screenshots :)

Don't take this post as criticism, but rather constrictive feedback. If the top two remarks are taken care of, I'll have another look and probably link to the documentation from the project page.

Thanks for the effort so far guys!

Pierre.Vriens’s picture

Pierre.Vriens CreditAttribution: Pierre.Vriens at In Petto commented

The "green buttons" are gone now. While cleaning that up, I also slightly adapted the outline of the various pages.

About the 8.x version: please note that "this" issue is related to the 7.x version, and about 80% of the currently reported installs are using that version. Moreover, in my experience, maintaining 2 sets of documentation (1 for each release) is a kind of nightmare. Instead, it is way more efficient (and clear?) to mark/highlight differences between releases where appropriate (eg: the D7 version does not have feature X, which is new as of D8). As a compromise, feel free to already create a separated 8.x subpage somewhere within the docu, in which I recommend to include "What's new in D8 (as compare to D7) items". But remember that "IMO" D7 docu has more priority right now.

Looking forward to see "the link" appear on the project page soon ...

PS: regarding links from docu to issues. For me, these links only exist as a kind of placeholders / bookmarks, to point to docu hidden in specific issues. After appropriate community pages are created from it (like the new HowTo-subpages @Rustan already created (merci), the corresponding links should be removed (of course). Open to better suggestions to create an inventory of valuable docu hidden in the issue queue (I don't know a better one for now though).

Rustan’s picture

Rustan CreditAttribution: Rustan commented

I also think separate 7/8 versions are useful. I added such, and moved around the relevant child pages. When the 7.x documentation is a bit more mature the parts that are the same can be copied over to 8.x branch. The structure is now quite similar to that of OG, which might help in itself as many will probably evaluate both of these together.

Most of Kristiaan's requests are now done, although there are no screenshots and the deepest pages are just placeholders.

Rustan’s picture

Rustan CreditAttribution: Rustan commented

@Pierre: You added an extra row to each of the use case pages, like "Creating sub-communities is yet another usecase for the Group module.". Do you think that is needed? I think it is pretty clear from the book structure that the documentation page is indeed for the Group module. If it is needed there, then it is needed on all documentation pages and the general documentation structure is broken? I see no specific need to have those notes there compared to on the other pages.

Pierre.Vriens’s picture

Pierre.Vriens CreditAttribution: Pierre.Vriens at In Petto commented
Title: Create Group module documentation » Create Group module documentation for D7
Issue summary: View changes
Status: Needs review » Reviewed & tested by the community
kristiaanvandeneynde’s picture

kristiaanvandeneynde
Primary language Dutch
Location Antwerp, Belgium
CreditAttribution: kristiaanvandeneynde at Deeson commented
Status: Reviewed & tested by the community » Fixed

I've done the restructuring to split up the D8 and D7 documentation. While I agree the idea behind the module remains the same, there are truly some different ways of doing things in Group 8 compared to Group 7.

I therefore thought it useful to keep the use cases, additional resources and contributor's guide at the top level, but move everything else under Group 7 for the time being. If a guide still holds true for the D8 version, we should clone that page so we can at least add screenshots showing the D8 admin UI.

Adding link, thanks for the effort guys!

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.

Melissamcewen’s picture

Melissamcewen CreditAttribution: Melissamcewen as a volunteer commented
Assigned: Pierre.Vriens » Melissamcewen
Status: Closed (fixed) » Active

I'll be updating some documentation here as part of a project if no one minds. Would love your feedback. Already fleshed out https://www.drupal.org/node/2723913 a little more.

Pierre.Vriens’s picture

Pierre.Vriens CreditAttribution: Pierre.Vriens at In Petto commented

Thank you Melissa for stepping in. Great to see others do have interest in documentation also! I like what you alrready updated in the docs. Personally I'd like to see (way) more docu about each of the submodules (they each have their individual stub-page already).

However, I'm not sure what the added value is of this issue being reopened. Also because producing docu is a "never ending story" (so this issue would remain open forever, no?). Instead, anybody interested in following what's happening in the community pages can just go find out in those pages there. I don't think using an issue like this one to describe the updates that were applied is really needed, would you agree?

Apart from that, since I started this community docu effort, some of it has been restructured already (by others). And part of the docs have been split between D7 and D8. I think that split is NOT a good idea, because already after a few weeks I see duplication of info, like "D7" in the tile of a D7 child page ... or within the D8 page there is now a reference to some recent D8 video, which I already added in the "Additional resources" also (indicating that it was about the D8 version). Therefor, IMO, splitting community docu about a module in multiple child pages (by version) should be avoided whenever possible. Instead, if there are release specific things, they should be indicated as such (eg: that same recent video is about D8, as indicated in the link title of it). On the other hand, a page like "what's new in the D8 version makes perfect sense" (= ideally a 1 page summary of anything in D8 that differs from D7).

kristiaanvandeneynde’s picture

kristiaanvandeneynde
Primary language Dutch
Location Antwerp, Belgium
CreditAttribution: kristiaanvandeneynde at Deeson commented

Hi Melissa and thanks for wanting to work on the documentation as well!

If there's anything specific you aren't really sure about, feel free to ask. Perhaps Pierre is right about leaving this issue closed and additional questions deserving their own support request issue. It can help keep follow-up questions or discussions narrow and topical.

As I'm currently swamped preparing my Milan session, it may take a while for me to provide some feedback on the changes you've made, but don't let that stop you from working on what you are sure of. Any help is appreciated, really :)

@Pierre: I still strongly believe in a split between the D7 and D8 versions. Even if only for the D8 core and D8 Group interface changes. I don't care about having to duplicate some of the page content if it means it can be accompanied by a screenshot which accurately represents the version you're looking up documentation for.

izmeez’s picture

izmeez CreditAttribution: izmeez commented

Just read a blog from @amitaibu http://www.gizra.com/content/og-message-stack-drupal8/ in which there are some positive comments about the group module. He also raises a couple of points that I would like to obtain clarification on as we have used og for many years and have not tried group module:

One of the core concepts of Group is that a group isn’t a node. It’s a Group entity. That’s fine, also OG can have any entity as a group, but I’d argue that 90% of the time your group should be content. Because more often than not, groups need to have published/unpublished status. Or because groups need to have privacy options, and even in Drupal 8 we have only {node_access} table, not an {entity_access}.

Furthermore, there are quite a few cases where a single group content should be attached to multiple groups. This is where the power of OG kicks in, doing all the heavy lifting of making sure permissions are being handled correctly. I can assure you this is not a trivial task.

1. Does group module support private and public groups?
2. Can group status be changed to published/unpublished?
3. Can single item of content be attached to multiple groups?

Thanks in advance.

izmeez’s picture

izmeez CreditAttribution: izmeez commented

I found issue #2317195: Allow more than one parent by node / subgroup that may be related to question #3 in comment #23.

izmeez’s picture

izmeez CreditAttribution: izmeez commented

I also found issue #2559135: Not using node grants creates a general incompatibility with other Drupal funcionality with patch that was committed along with a comment:

By default Group7 trumps all node access modules. If Group has nothing to say about access, then node access can have its way. This patch allows Group to play nicely with other node access modules, provided you set it to "Compliance mode" in the settings.

In Group8, there is only compliance mode as the other "Safe mode" was too confusing. The downside to "Compliance mode" is that people need to be more careful about which node access modules they want to use along with Group.

kristiaanvandeneynde’s picture

kristiaanvandeneynde
Primary language Dutch
Location Antwerp, Belgium
CreditAttribution: kristiaanvandeneynde at Deeson commented

Hi there, below are my answers to your questions. Although next time, please create a separate support request.

1. Does group module support private and public groups?

Yes, by simply assigning someone the permission to 'view group', they can see the group. Anyone without the permission will not see the group.

2. Can group status be changed to published/unpublished?

No, even though Amitai argues this is a great reason why people want groups to be nodes, I've found most of the time people don't want to unpublish groups. You can make them fully private, if you wanted to.

3. Can single item of content be attached to multiple groups?

Yes and no. Yes in the D8 version, no in the D7 version unless you apply the patch from #2317195: Allow more than one parent by node / subgroup. Please keep in mind that patch will be committed once my colleague and I get around to it. So it's definitely safe to use!

Pierre.Vriens’s picture

Pierre.Vriens CreditAttribution: Pierre.Vriens at In Petto commented
Issue summary: View changes

@Kristiaan: please DELETE the content of your last comment before this one (or move it to a new issue). THIS issue's purpose is to track enhancements to this kind of documentation. For as long as you leave your comment nr 26 in there, you're basically approving that users who are too lazy to create new issue, start polluting issues like this one. FYI: I've used the "report as spam" for the 3 comments preceding your last comment (which are currently nr 23, 24, 25). BTW: this issue is about D7 (it's even in its title), NOT about D8, remember?

izmeez’s picture

izmeez CreditAttribution: izmeez commented

@kristiaanvandeneynde Thank you for the answers to the questions.

I added the comments to this thread because I thought the questions, that are about BOTH group 7 and 8, might be of interest to those working on the documentation pages. I did not want to create more issues for a busy module queue.

@Pierre.Vriens I am surprised by the aggressive tone of comment #27. Not very good for an open source community. The first time I have encountered such a response in over eight years with drupal. These are very real questions people have when considering the Group module and I thought this thread could help flesh out info to add to the documentation pages.

scotwith1t’s picture

scotwith1t
Location Birmingham, AL
CreditAttribution: scotwith1t at Mobomo for Mobomo commented

Yeah, what @izmeez said! I get the need to scold some more casual Drupalers to get them to follow the process, but it looks to me like @kristianvendeneynde has made every single commit to this module, and probably should be given a little slack about how he handles the issues in his own module's issue queue. Just sayin'. That out of the way, I'm sure your contributions to this module's documentation are stellar and helping folks every day, so thanks for that!

Soul88’s picture

Soul88
Primary language Ukrainian
Location Ukraine
CreditAttribution: Soul88 commented
Status: Active » Closed (outdated)

We thank everyone for their collaboration on this issue, but as the D7 version is no longer supported, we will now close all D7 issues to keep the issue queue a bit tidier. This information won't go anywhere, it just won't show up on the list of open issues anymore.

Please see: https://www.drupal.org/project/group/issues/3203863#comment-14100281 for more details.