Problem/Motivation

While this project uses Markdown in an attempt to offer both humans and agents useful and practical advice, at the end of the day agents are definitely the primary audience consuming it, and folks searching for information will be very unlikely to end up in some random markdown file in a Git repository.

Where they're far more likely to end up is Drupal.org's documentation, so let's create a place for that to happen.

Proposed resolution

Write it :)

Remaining tasks

CommentFileSizeAuthor
#5 IMG_5977.png407.56 KBwebchick

Comments

webchick created an issue. See original summary.

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented
Issue summary: View changes
webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented
Issue summary: View changes
webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented
Status: Needs work » Needs review

Ok, this is definitely not DONE yet, but it's in a decent spot for review, I think.

The "median Drupalist" at DrupalCon I would say was someone with VERY deep Drupal knowledge and experience who has maybe horsed around with AI periodically but definitely not been blown away by it. As a result they lean skeptical of bold hype-filled AI claims, and want practical advice of how it will be helpful to them.

They may also as a result need a bit of "catch-up" material covering what's been happening in the AI space over the past 12-18 months.

Because this stuff moves FAST, I'm trying to avoid very detailed, step-by-step instructions, and also trying to avoid pointers to specific projects, instead pointing at places to FIND those specific projects.

Anyway! Here we are. The docs section now has:

Would love folks to take a look and share their thoughts.

Still to come:

- AI tools for Drupal contributors
- Security and contrib considerations
- Community resources
- [your awesome idea here :)]

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented
StatusFileSize
new IMG_5977.png407.56 KB

Um, wow! Another benefit of doing this, it turns out, is the SEO is near instantaneous, apparently. 🤯

I was trying to remember the name of the project that catalogues all of the various Drupal AI tools (https://github.com/AJV009/awesome-drupal-ai ) and searched for it in Google, and the page I published like 4 hours ago is #1 in the results. 🤪

rakhimandhania’s picture

rakhimandhania commented
Issue tags: +AI Innovation, +AI Initiative Sprint
marcus_johansson’s picture

marcus_johansson commented

I have read the documentation and usually I would say that using em-dash is the first sign of AI usage people get angry about, but in this case I think it fits :) I love that "Vibe coding" accumulates debt fast. was added. In general for me it looks great - I have some nitpicks, but therein lies my larger question.

Is there some reason not to use Gitlab and this project? If we used Gitlab, it would be a normal MR like any other and it would be easy to give suggestions, add comments etc.

I'm not sure what the recommended way of doing Drupal documentation is, but since Gitlab is being used by Drupal and the Drupal Gitlab template has a documentation template built in by using it, I assume its there for a reason?

All you have to do is provide a mkdocs.yml and some markdown files and you can use any markdown editor of your choice or let coding agents help you write the documentation. They are moving to zensical now, but its a similar system.

With the AI module we have added mike on top of mkdocs, meaning that documentation is completely versionized also in its public facing documentation. I think this is what is lacking in Drupal core documentation for it to shine with coding agents. They (and humans) always had a problem using methods that exists in some other version while coding, because its referencing some unversioned documentation. If all modules had docs folders and the current versions docs in it, the coding agents could just get the repo in the right version and reference this. With d.o docs, you never know what they reference.

Just my two cents - in general I would RTBC the content of the documentation, it looks great, but someone else should have a look as well.

marcus_johansson’s picture

marcus_johansson commented

One thing that is not a NIT, on https://www.drupal.org/docs/develop/development-tools/ai-coding-tools-fo... the "Setting up AI tools for a Drupal project" links to 404.

poker10’s picture

poker10 commented

My 2 cents are that if this is a part of the standard docs on d.o., the discoverability is way better as compared with the separate project.pages.drupalcode.org URL (you need to know about the project to access this specific docs link, or rely on the SEO/Google). Not sure if anything changed recently, but there was still an issue with discoverability of project.pages.drupalcode.org docs pages last year.

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented

Is there some reason not to use Gitlab and this project? If we used Gitlab, it would be a normal MR like any other and it would be easy to give suggestions, add comments etc.

Haaa, mainly because my Drupal knowledge is ~5 years out of date and pre-dates GitLab, so I only really know "old school" methods. 😅(I'm working on learning it now!)

However...

I'm not sure what the recommended way of doing Drupal documentation is, but since Gitlab is being used by Drupal and the Drupal Gitlab template has a documentation template built in by using it, I assume its there for a reason?

The main reason is SEO (what @poker10 said). Drupal.org has been a website for 20+ years and as a result has INSANE trust, so Documentation pages (nodes) get indexed almost immediately. (See #5.)

A good example of this is searching for "Drupal coding standards" — the first link in Google is the (now obsolete) set of coding standards in the handbook. (This is also the one LLMs stubbornly keep citing by default.) The second is the project Drupal Coding Standards, but not the actual web section powered by GitLab https://project.pages.drupalcode.org/coding_standards/ until result ~#10.

I think for things like coding standards, or for the AI module docs, where a line-by-line diff and being able to tag versions of docs is incredibly useful, GitLab is a fantastic place to put it. But for "narrative" docs, like this, nodes are probably fine, and can point off to those places.

One thing that is not a NIT, on https://www.drupal.org/docs/develop/development-tools/ai-coding-tools-fo... the "Setting up AI tools for a Drupal project" links to 404.

Yep, I haven't scaffolded out that page yet, was hoping for an interim review of what's there so far. Thank you so much for the thoughtful review!