Add noderef field for project to doc pages

that sounds fantastic.

the only theoretical tie right now is that the path aliases (where they exist in the handbook match) eg.:

http://drupal.org/project/translation
http://drupal.org/handbook/modules/translation

i think this could make a good part of our roadmap to better docs.d.o

+1

CCK and node_reference are soon to be added to drupal.org.

adding tags (to review at meeting this wkd) - this should be moved to the infra queue if approved

OK. At today's meeting in Vancouver, we made this into a concrete proposal.

We would like to have an optional, multiple-valued, node reference field called "What does this document" (or perhaps "Related projects" or something similar) added to all Handbook pages. The values would be Project nodes, and the idea would be to mark a particular page as being related to a particular project (Drupal core, a contrib module, a particular contrib theme, etc.).

Once that is done, it would be helpful to list somewhere on the Project page (perhaps in a separate tab) all of the Book nodes that are marked as documenting that project.

I'm upping priority on the highest-priority issues for docs team infrastructure.

closing as duplicate to #995292: Noderef field on issues for Documentation project

This is not a duplicate of that other issue, actually.

This issue is asking for Book nodes to have a noderef for a Project(s) that they refer to.
The other issue is asking for Issues to have a noderef field for the Book node(s) they refer to.

oops, sorry! i re-read them a couple times because it was a bit confusing, thanks for re-opening!

this sounds great. what is this waiting on? is there a feature that adds the field to the book node type and the related view to provide a block to display on project nodes? i'm happy to help commit and deploy this once it exists and it's tested...

Do we have CCK on d.o?

If so, then the only thing this is probably waiting on is a patch.

Not yet, but there are now like 4 different efforts that need it. As soon as any of them have a viable, deployable patch, we'll install CCK. That's over at #651484: Enable CCK and node_reference ...

all of our comment killing related issues are pending on getting cck. ;)

right... so it's not a bottleneck. Just pick one of these and get it working on jhodgdon's dev site and we'll deploy it live. ;)

OK. I realized we need to think slightly about how this should work. Where should the field be in the book page editing form? Where should it be displayed?

My thought would be to have it just after Taxonomy in the edit form. We would use an auto-complete field, allow multiple entries, and display it with the taxonomy/status block at the top of the book page. Any other ideas?

Comment #4 above also references making a list on each Project page (or a tab of the Project pgae) of related doc nodes... I'm not sure how this would work (especially if Drupal Core is one of the projects -- wouldn't nearly every doc page be related to Drupal Core?), or how the list should be displayed or ordered.

Since we have some more thinking to do, temporarily moving this back to the Doc issue queue.

Re: how this looks on project pages: could be a block that points to a "more" page display that's a new tab off node/N (node/N/documentation?). This block and page could be hidden for core, since yeah, it's probably going to be insane. We might consider removing core from the possible projects to reference with this, since it's pointless to tag everything for core IMHO. This is a proposal for contrib docs, no?

#16 - That makes sense, assuming node/N is a Project node, and the block with the "more" link would be on the project node itself.

Agreed on the logic of not doing this for Drupal Core. We could probably call the field "Contrib projects documented" (or something more concise preferably) so that people would know only to choose contrib projects, or I suppose we could use Noderef's Views capability to remove Drupal Core as an option completely.

+1 on 15 re: where it should show on docs pages/book page edit form.

not totally sure if the docs pages should be listed on project pages - there should be the usual single link from the project page to its main docs landing page, and then the subpages are there. so that part seems redundant to me.

i think that the autocomplete should list core but that for core, it should just link back to http://drupal.org/project/drupal (and obviously core doesn't have its own docs section, so that is pretty moot).

OK.... I still think it could be useful for a project to have a View that would let people find related doc, just in case it wasn't all collected together... but maybe we could just add this to the Handy Dandy Docs Management view (http://drupal.org/documentation/manage), so people could search for this doc if they wanted to?

So here's a proposal:

1) Book pages would have a new Nodereference CCK field (choices would be Project nodes; field would be optional, auto-complete rather than drop-down, and multi-valued). The field would be called ... still not sure about a field name?
- Projects this page documents
- Related projects
- What does this document
- ???

2) This field would appear just after Taxonomy in the node edit form.

3) On the Book node page, it would show up in the yellow meta-data block at the top of the page (along with taxonomy and last update date).

4) The Project filter would be added to the docs management view (http://drupal.org/documentation/manage), so you could search for all doc related to a particular project there.

5) Optional: we could add a link to the Project page sidebar (except for the Drupal Core project) called "Search for Documentation" that would take people to the doc management view (http://drupal.org/documentation/manage) with this project selected in the filter. I think the doc management view is only available to people who are logged in though (maybe?)... is that true?

Thoughts? Any ideas on item 1 (name of the field)?

I just logged out and confirmed that the doc management view is only available to logged-in users.

Re comment #19 :

1) Related projects +1
2) Sure
3) Could that get crazy if there were too many projects referenced? (Maybe sidebar instead? Or somewhere else?)
4) That'd be great
5) Hmm... yes, this could be good but it's also a little redundant to the main site search. But at least adds some extra filtering.

RE comment #21 -

3) I think if the format was something like:
Projects Referenced: proj_a, proj_b, proj_c
it wouldn't be terrible. I don't think most doc pages pertain to more than one or two projects (if they pertain to everything, they should probably not have a marking because why would that be useful?

Regardning (5) in #19 – what do you think about adding a "Documentation" tab on project pages, listing all docs pages linking to the project?

RE comment #23 - maybe. The problem would be that for Core (and maybe some contrib modules), this would be a huge amount of docs. Not sure what that page would look like either.

so, it sounds like having code ready to push for one of these is what will lead to getting CCK actually on d.o (not the other way around). is this the issue closest to ready or is there another that'd be easier to finish? we should maybe pick one to drive forward so at least we have cck/noderef to work with going forward.

See #651484-33: Enable CCK and node_reference. CCK + node reference are actually deployed, just not yet enabled. ;) Basically, don't worry about it. Just work on whatever itch you have and assume CCK + node reference are available tools, since they will be by the time any of these are ready to go.

Oh sweet, good to know. :) Thanks Derek!

It would be very nice if this could be used to automate some of the module info on module comparison pages like http://drupal.org/node/418616. If I'm comparing several modules with similar functionality, the single most important piece of info is whether it's available for the Drupal version I'm running, but stuff like that is impossible to maintain manually.

Suggested info to show on docs pages:

- Module name with link to module page
- Which versions it's available for, and if it's dev/alpha/beta/full release (ie. show latest recommended release for each branch, or latest non-recommended if there's no recommended version, with colour coding as on the project page)
- Maintenance status
- Development status
- (and maybe module categories, if it doesn't make things too crowded)

We can show it in a table just under the header. If the doc page is just about one or two modules, the automated info won't be too much in the way. If the doc page is a module comparison page, the table will be pretty big, but then it will also be the most imporant piece of content on that page.

zirvap: I think #28 goes beyond the scope of this issue. All we are talking about here is having a noderef for project nodes, which would generate links to the project pages for the modules being compared. Building something that shows all that other information automatically would be a lot more work, and IMO would block any progress on this issue.

jhodgon: Good point. I'll keep those suggestions for a future improvement, after this is implemented.

i'll try to implement it

I edited the original post with a wrapup of the discussion, using mainly the #19. I tried to make it exact, ommiting any discussion. That doesn't mean i don't want any :). Suggestions and improvements are welcome. I might end up making it more exact once I manage to download the stuff (waiting to be approved at #1274506: I want access to bzr+ssh://drupal-redesign@util.drupal.org/ ).

I think it will be okay to use the same dev site as http://drupal.org/node/995292#comment-4972320 for this, but I'm not completely sure. I haven't fully read through either issue.

I think it's probably Ok to use the same dev site for both, if the two people working on these two issues can coordinate, and as long as their changes can be kept separate when we go to make patches. But it might be easier for everyone if we kept them separate?

the first part (points 1 - 3 above) can be seen here :
I deliberately put the projects above the date - it felt better.

http://docnoderef-drupal.redesign.devdrupal.org/node/960926 - 1 project
http://docnoderef-drupal.redesign.devdrupal.org/node/580026 - 2 projects

To test the editing part : I am not sure I can disclose the password here ? If you drop me a line, I can change yours, since the server doesnt seem to send emails.

the view can be seen here :
http://docnoderef-drupal.redesign.devdrupal.org/documentation/manage

the control for projects is not exactly nice ...

thanks for any comments

Regarding editing tests, what people often do is to create a new account with user name "bananas", password "bananas" that people can use to log in and test on the dev site. We also can't see the documentation/manage page without a login account.

The two book pages look fine to me though! Thanks!

bananas delivered :) please have a look at the wording (field help on the edit form).

Thanks for the bananas. :)

I took a look at the Doc Manage/Status page. I think the Related Projects box should just be a single-select drop-down list (it will be more compact that way). Or a type-ahead auto-complete field, which might actually be easier to use, since the list is *very* long.

Regarding the help/description text for the Related Projects field...
a) Should start with a capital letter and end with "." (right now it looks a bit unprofessional).
b) Since you've limited the number of projects field to 4 anyway, it's not necessary to mention that you can't enter more than 4 in my opinion... Oh wait, you can add another item...

How about this text, to get across the same idea (I think):

The project(s) that this page documents. Do not include "Drupal core" or projects that are not the main subject of this page.

Description made professional, thanks :).

Regarding the views filter : i totally agree, an autocomplete will be nicer. But it will require some coding ( think I ) and I wanted to have a functional piece done :).

(I tried hard to capitalize where appropriate :).

I think that if you make it a single-valued filter, you will get a drop-down list, and you might have the option of an auto-complete... I think? Check and see. Choosing one value for the filter is I think enough for that page. The idea would be that someone would be trying to find a page to work on that is related to a module they're interested in, and one value at a time should be enough. All the other filters on that page are also one value.

Thanks!

Sadly, node references don't support autocomplete for exposed filters. :( #506654: Autocomplete for nodereference Views exposed filter Another casualty of the "fix it in HEAD first" workflow. Probably never going to happen for D6 now, even though there was a working patch nearly 2 years ago...

Too bad, drop-down will be fine then. :)

my friend did the filter auto complete recently so i should be able to do it easily - next stage probably :)

in case you feel this is suddenly too slow or without reply, it is because i am offline for a few days. thanks.

mojzis: check out the new mockup:
http://drupal.org/files/issues/docs_ideal_wf_v4.jpg

I just marked
#1184686: Module documentation tab
as a duplicate of this issue. You might take a look and see if there are any additional details that would be useful here.

mojzis - are you back, and how is this going? The parent issue of this has a slightly different design, but we still need to get this done as soon as we can. Please post status if you can. Thanks!

wrapup of discussion

I just edited the issue summary slightly.

Since the docs pages are now going to be "community documentation", what I think we want to do here is not make the view that shows all related docs for a project be a full-fledged Documentation tab showing in the project page.

Instead, I think there should be a view that can show all docs pages related to a project, and it should be called "Related community documentation". And each project should have an automatic link on the sidebar that says "Related community documentation".

This view/link would work the same as the one that we added for change nodes -- for instance, go to http://drupal.org/project/drupal and you'll see at the very bottom a link for "View change records", which takes you to http://drupal.org/list-changes/drupal

Similarly, I think this view would be at http://drupal.org/list-docs (or something like that), and it would have an argument so that list-docs/[project-short-name] would show you the docs for a given project. And each project would automatically have that link showing up in the Resources section of the sidebar.

Hope that makes sense...

I continue to think the better solution for project-centric docs on d.o (and a host of other problems) is to enable OG, tell it that project nodes should be groups, and allow doc pages to have a project audience. See drupal.org projects as Organic Groups for more. We'd still have a view on project pages showing related community docs -- it'd just be using the group, not a node ref to the project. In terms of this specific problem, either solution would be basically equivalent. But using OG would solve a bunch of other problems for us at the same time, so if we're going to put effort into something, it might as well be the plumbing that enables other sinks and faucets. ;)

That said, deploying OG on d.o might be a bit more of a fight, and we've already got CCK + noderef, so in terms of shortest path to deployment, plowing ahead with the current plan makes sense.

Just wanted to raise it for consideration.

Cheers,
-Derek

That sounds like a reasonable future plan dww... I also want to have an "official" area in the curated docs for each project (and that will be a lot more structured, topic oriented, etc.). See #1291058: Discussion: Make a curated docs section/system for that discussion.

Right now, I'm guessing that making each project an OG is unlikely to happen soon... it shouldn't be too hard to convert the node refs to OG refs later if it ever gets deployed, should it?

Tagging so it doesn't get picked up by #1421874: [meta] Documentation Issue Queue Cleanup

I destroyed the docnoderef dev site for this since work hasn't gotten very far and it is stale. Please ask for a new dev site if you are planning to spend time on implementation.

Modify the last item so it's not a doc tab but a community docs link

There hasn't been work on this for 11 years. Is there interest in pursuing this?

I don’t think this is relevant now.

Projects have a documentation link field which can go anywhere, since things like documentation in GitLab pages are effectively off-site.

Documentation on Drupal.org has related content that can include projects, or any other content.