Hi,

I have been bashing my head trying to figure out some of the basics of setting up the project* modules. In retrospect some of the things I've been wrestling with would've been super simple to resolve if there was just some basic documentation about how to setup & use these modules. Am I just missing where the documentation is? I know this is mainly focused on providing support for drupal.org, but it would be really great to make it easier to use for other sites. I also know there is a lot of development going into this set of modules, so if its too late to get some documentation on the current version, can there be some effort put into developing documentation for the upcoming version?

Thanks,
frustrated user

Comments

dww’s picture

dww
we/he/they
commented
Status: Active » Fixed

http://drupal.org/node/114618
README.txt INSTALL.txt and UPGRADE.txt shipped with the module
that's about it, sorry...

see http://drupal.org/node/87175 for more about this.

also, now that you've bashed your head against the wall and started to understand, you're in the perfect position to help document things that were confusing to you. please help out as much as you can, and it'll get better.

thanks,
-derek

aclight’s picture

aclight commented

@rcross--Can you be specific about what things were hard for you to figure out? I have written a lot of documentation for my own site about project module but it's all targeted to end users, not administrators. What administrative/setup/configuration topics would you like to have seen?

rcross’s picture

rcross commented

It would be nice if a link to this page http://drupal.org/node/114618 was included on the module home page as part of the documentation links. That is a first and simple step, and would've answered a few initial questions.

I should also apologize for not looking at the readme.txt to begin with, but upon looking at it I don't think that would've provided any more help than reading the project description on d.o

The release notes link don't really help at all since its mainly just a list of resolved issues.

The things that were "difficult" for me was the un-intuitive way of doing a few things (without documentation to fall back on). For example, my first question would've been easily solved - "how to I define project types" since I figured it would be in the project administration pages. Also, because the only administrative setting is the number of projects per page (when project types/categories isn't defined) it seemed like i was missing an extra module or some custom programming or something.

After I hunted around and realized the taxonomy was the way to create project types, I tried to do this and realized that I went from a list of all projects to a page of project types (without an intuitive way of showing all projects regardless of type, similar to the way a hierarchical taxonomy shows all nodes beneath it including deeper level terms ). Also, since I didn't really need a 2nd level of organization (categories within project types) it was difficult to figure out how to just list all projects within a certain type. I actually think that it would be ideal to switch the defaults of the module to be by name first and include all listing ways (name, category, date). The reason this was particularly un-intuitive, was because I had only seen the setting for projects per page on the settings page - so it never really occurred to me to go back to that page to make changes on the listing format. Again, this wasn't really "hard" - but without some simple documentation mentioning something to this effect it was not very intuitive to figure out. It was also really unclear as to whether I needed to have a release for a project before it showed up in the list, or whether that release needed to have certain attributes for it to show up. As it is, my next fumbling step is to figure out how the releases stuff works and integrating the "project release api compatibility" taxonomy vocabulary. There doesn't' seem to be a lot notes on how that is supposed to work (including things like the version numbering details and how it relates to a release api number), so please point me in the right direction if there is - mainly regarding projects/releases showing or not showing under certain conditions. For example the drupal.org webmasters project never shows up in the project listing, so I don't know how people ever find it (maybe this is on purpose). Also, I have about 50 projects already in the system, so every time I make changes I have to figure out whether or not that requires me to update each project/release. I am looking for basically the same setup as drupal.org in a lot of ways, so maybe even just a detailed writeup about how drupal.org uses the project modules would serve as a sufficient tutorial - like how would you create the project setup for drupal.org from scratch?

Anyways, I hope that helps clarify my frustration.

P.S. Some other idiosyncrasies I noticed
- how to change "Project Types" to say something different, i.e. "Module Types" or whatever. It seems like project module depends on certain taxonomy vocabularies being named specifically.
- As I mentioned, its kind of unclear as to when a project/release will or won't show. I feel like i need to create a matrix of different configurations and project properties and its display status.

dww’s picture

dww
we/he/they
commented

This is *very* helpful input, thanks. aclight's already addressed some of this recently by making some edits on the handbook pages, so please take another look and help further refine them.

It would be nice if a link to this page http://drupal.org/node/114618 was included on the module home page as part of the documentation links.

Sorry about that... duh! Now fixed. ;)

I am looking for basically the same setup as drupal.org in a lot of ways, so maybe even just a detailed writeup about how drupal.org uses the project modules would serve as a sufficient tutorial - like how would you create the project setup for drupal.org from scratch?

There's the drupal.org install profile: http://drupal.org/project/drupalorg_testing
It's true, a write-up about this would be great.

dww’s picture

dww
we/he/they
commented
Status: Fixed » Active

Forgot to mention, it'd be great to turn these into separate issues as UI bugs:
- Include a link to the project vocabulary via the project admin settings pages (with help text).
- Add more flexibility for the project vocabulary so that it can work as a single-tier tags vocabulary, not just a tree.

And these as separate documentation tasks:
- Include a description of how this vocabulary currently works in the INSTALL.txt file (and a pointer to it from the README),
- Add more docs about how taxnomy effects releases.
- Add more docs about how releases interact with issues and projects.
- Write-up the d.o testing install profile/d.o's project* configuration.

There might be a few other concrete, specific suggestions in your summary, so feel free to submit anything you feel I've missed. Once that's done, someone should post all the links here so interested parties can easily find them. Then we'd move discussion/effort into each issue, since different people could work on each one. Otherwise, let's continue general discussion about kinds of things we need to document over in http://drupal.org/node/87175 and we can just close this one.

Thanks again,
-Derek

aclight’s picture

aclight commented
Status: Active » Fixed

I've added the issues mentioned by dww above as follows:

And one more issue that dww and I spoke about in IRC:
http://drupal.org/node/193526: Remind user to configure project* taxonomy after install

aclight’s picture

aclight commented

@rcross--As dww said, thanks for your comments.

Since your original question, I've added and revised a lot of the project* documentation. I think I've addressed all or most of your concerns from comment #3.

If you don't mind, could you read the documentation starting at http://drupal.org/node/114618 and let me know if you think I didn't go into enough depth on a certain aspect of one of the modules or if there is still information missing.

When I was setting up project* on my site I had many of the same questions/problems as you have pointed out here. But that was about 6 months ago, so I've forgotten about most of them by now :)

It's good to have someone who is going through this with a fresh perspective to help us find out where the documentation is lacking.

To specifically address a few of your concerns:

For example the drupal.org webmasters project never shows up in the project listing, so I don't know how people ever find it (maybe this is on purpose)

I think that's because there is no release for the webmasters project, and so it doesn't show up (see http://drupal.org/node/193635#project_item1 for more details).

how to change "Project Types" to say something different, i.e. "Module Types" or whatever. It seems like project module depends on certain taxonomy vocabularies being named specifically.

See configuration section of http://drupal.org/node/116527

rcross’s picture

rcross commented

Wow guys, thanks! I honestly thought I was just going to come off as a complaining newbie. I'm glad the feedback was useful.

Also, a little clarification of a single taxonomy issue. When I initially wrote that up, I was mainly just suggesting that the module's default sort option should be by name, which would allow for modules to be listed by default if no categories are specified (as opposed to trying to show it by category which produces nothing). However, on restrospect, I think it would be good to allow for a single taxonomy for the project module, since this would provide the ability to have categories for projects without having different project types (or specifying an arbitrary type).

I will read through the revised documentation in the next few days and provide some more feedback if I can. Thanks again!

aclight’s picture

aclight commented

@rcross--I see your point about browsing by category vs. browsing by name. I think this will be a non-issue once we get project* to be views enabled, which hopefully won't be too long from now.

As for using single tier taxonomy, that's essentially what I'm using on my site (www.igorexchange.com), though I'm doing so under the two tier constraints made by project module. So, my "Project type" vocabulary basically looks like this:
Project type:
packages
--Analysis
--Graphing
--Programming
--etc.

In my primary links menu, my "Projects" link just links directly to /projects/packages, so this is largely transparent to the user. Plus, now I have the flexibility that, if some time in the future, I need a new type of project other than packages, I can add that without having a bunch of linkrot, etc.

If you happen to check out my site and have any questions about how I'm doing something with project module, feel free to contact me via my contact form. Also, I've written pretty detailed documentation for using project* (from an end user's perspective). It's slightly specific to my site in places, but for the most part it's just describing how to use project*.

Anonymous’s picture

(not verified) commented
Status: Fixed » Closed (fixed)

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