This is a request to add a handbook for project documentation. The expectation would be that children pages would be for different projects. This is in light of not being able to have a wiki attached to each project.

In some cases you have modules (e.g. Views) that make sense to have their documentation under site building. In some other cases modules make sense to have their documentation under development (e.g. devel). Sometimes a modules wiki documentation works well to be associated with the module and project page. This could be for an install profile, a module, or a theme.

If this has already been discussed in an issue than I missed it in my search. I assumed it had already come up.

Comments

jhodgdon’s picture

Status: Active » Closed (works as designed)

We used to have all of the contrib modules docs in one place. Several years ago, they were reorganized so that they fell into the book/section that made sense. I think we need to leave them there.

Also, project owners can put a link on their project page to where the documentation is, so finding the particular docs should not be a major issue.

Anyway... we don't want to go back to the way things were. We have thousands of contributed modules an themes, and the point of putting them into Site Building, Admin, etc. is that people would discover that a module exists to help them with the task they are reading about.

mitchell’s picture

Title: Add A Book For Project Documentation » Make per-project documentation
Status: Closed (works as designed) » Active

I would like to extend this proposal and look at it a bit differently. Right now projects have to create their own documentation. It's not 100% obvious where it should go, and so many projects end up waiting for another contributor to make the choice for them or end up with a single documentation page that is their project page. Also, many never create a path alias, and if they do its using a structure similar to OP rather than the subsection where it exists.

I would like to solicit feedback for switching the path for projects I maintain, and possibly recommend as general pattern, from /documentation/modules/[name] to /project/[name]/documentation

>In some cases you have modules (e.g., Views) that make sense to have their documentation under site building. In some other cases modules make sense to have their documentation under development (e.g., devel).

Wouldn't it be much cooler if we could escape all special casing?
---
Unrelated side-noted (not the topic here): I would also like to see this generated automatically for all new projects with some structure based on the project.

jhodgdon’s picture

There is also a proposal (not sure where the issue is, perhaps infrastructure?) to make Projects essentially be Organic Groups, which would mean they could make their documentation pages and they would be grouped automatically. I'm not sure what the status of that is, but it might be relevant to this idea.

There is also a plan to make an official/curated docs system, such that each project on d.o would have a way to create and maintain its "official" documentation. That would probably take care of the need to generate docs for new projects.
#1549580: Track progress of building the Help/Docs System

Regarding the URL change, that would be a big change to how we've been doing things for quite a while (we do the same for core and contrib modules)...

Anyway, I'm a bit confused about what this issue is about now. It was originally a request to revert to having a separate Contrib Modules or Contrib Projects handbook, and now it seems to be requesting something else. Maybe it would be better to file new issues with your new ideas, one per idea, so we can keep them all separate? Just a thought...

LeeHunter’s picture

If I'm understanding the OP correctly, we have this now, but it may not be obvious.

A project maintainer can add a link to the project's documentation (which is essentially a wiki and can have child pages). Currently it can only be placed in one guide, although this will change in the future when we can assign pages to multiple maps. When we have that new mapping capability, we might want to have a separate Contrib Module book with all the projects automatically mapped to it (in addition to being mapped to the Site Building Guide or whatever) but this would probably be tucked away somewhere since it would be so incredibly massive and unstructured that it would have no value to most users.

I'd certainly like to see a slightly different workflow for creating project documentation. Right now, there's only a field on the project page where the project maintainer needs to enter a path. This means that they have to

- figure out where the page should live (which is not necessarily obvious)
- create the docs
- copy the URL
- return to the project page and enter the URL.

It would be nice if there was an "Add Project Docs" button which would do three things automatically:

- Create and open a new docs page
- Add the new docs page link to the project page (maybe only after the page is saved).
- Add an issue to the docs issue queue requesting that the new page be mapped to a book (or books).

I'm not sure how feasible this would be, but it would shift the task of positioning content away from project maintainers (who are typically not familiar with the content architecture) and over to the docs team. It would also give the docs team a chance to scan the new content for style or other issues.

Of course, we'd still need a docs link field that could be manually edited.

LeeHunter’s picture

Title: Make per-project documentation » Improve the integration between a project and it's related documentation
Issue summary: View changes

Changing the title to reflect the problem, which is that the process for associating a project with related documentation is entirely manual (i.e. it's awkward and requires an intimate knowledge of the documentation structure and processes to even get started).

jhodgdon’s picture

Adding related issue.

jhodgdon’s picture

Title: Improve the integration between a project and it's related documentation » Improve the integration between a project and its related documentation
joshuami’s picture

Issue tags: +d.o content strategy
eojthebrave’s picture

The content strategy work being done in #1133434: [META] Content Strategy for Drupal.org seems like it will help with this issue. Sounds like it will implement something like what is mentioned in comment #3. Make projects into organic groups. You could then create a documentation page within the group, so there is an association with the page and project. And, we could probably also do some things like automatically link to a projects documentation if it exists since we'll be able to easily see if there are any documentation pages in the group. This would eliminate the manual, and awkward step that Lee mentions in comment #5.

Seems like if that IA work gets done it would solve the relationship of documentation to a project problem, and then open things up to allow better automatic generation of navigation etc.

krina.addweb’s picture

Issue summary: View changes