Problem/Motivation

https://www.drupal.org/about/core/policies/core-change-policies/core-gat...

Steps to reproduce

Proposed resolution

Remaining tasks

User interface changes

API changes

Data model changes

CommentFileSizeAuthor
#6 3581687-documentation-guidance.patch9.42 KBwebchick
#4 3581687-documentation-guidance.patch12.6 KBwebchick
#2 joe - docs.txt19.18 KBwebchick

Issue fork ai_best_practices-3581687

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

About issue forks

Comments

webchick created an issue. See original summary.

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented
StatusFileSize
new joe - docs.txt19.18 KB

Here is the raw transcript from @eojthebrave and my conversation around Documentation best practices.

eojthebrave’s picture

eojthebrave
he/him
Primary language English
Location Minneapolis, MN
commented
Issue summary: View changes

Adding links to the some of the things mentioned.

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented
Version: » 1.0.x-dev
Status: Active » Needs review
StatusFileSize
new 3581687-documentation-guidance.patch12.6 KB

Ok, pointed Claude at this issue and the transcript, here is what it came up with.

webchick’s picture

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

Oops, my bad, that had some hunks from #3581672: Guidance on writing excellent automated tests in there.

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented
StatusFileSize
new 3581687-documentation-guidance.patch9.42 KB
zorz’s picture

zorz commented

Maybe it would be nice to have an example of how a good documentation looks like and have the eval system tinker the skill until the score is good enough.

webchick’s picture

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

That’s a great idea!

And we probably want that “what does good/bad look like” for each type of documentation, too. (Eg handbook vs API vs README)

I wonder if it’s possible to gather data about this? 🤔 Like Google analytics or whatever to show a combo of 1) popular in terms of views and 2) people are spending time on the page and actually reading it vs bouncing.

hestenet’s picture

hestenet
He/Him
Location Portland, OR 🇺🇸
commented

This is analysis recently done by the Pronovix team as part of an STA grant to support some documentation improvements - would this help?
https://docs.google.com/spreadsheets/d/1QZXAVnVf2wKdpL-8t3y1CtuoFhyaRFPa...

hestenet’s picture

hestenet
He/Him
Location Portland, OR 🇺🇸
commented

For that matter, they also produced a number of other artifacts, including things like templates and a contributor checklist: https://drive.google.com/drive/folders/1EOXk8BfvycxpTyVRZzWlvG2MSH6Qetpy

mgifford’s picture

mgifford
he/him
Primary language English
commented

This is an initial effort to create a generic content style guide to an AI - https://github.com/mgifford/STYLES.md

Documentation is one type of style we have to maintain.

  • 2c5bed25 committed on 1.0.x 
    feat: #3581687 Add documentation guidance skill content

Co-Authored-By...
webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented
Component: Code » Guidelines
Status: Needs review » Fixed

OOOH, that analysis is AWESOME! :D Thank you so much for sharing!

Ok, what is currently in the repo is purely a stub (Claude called us out on it in #3583237-1: Agents' review of our project :) :P), and #6 is at least better than nothing, sooo I've committed that (with Claude's help to get it to re-apply on top of the current source) as a starting point to build from.

Spun out #3583241: Add evals for how-to-write-documentation.md to discuss adding "good" example(s) and evals to this guidance, pointing to the data in #9 and #10.

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

webchick’s picture

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

Grrr also spun out #3583245: Guidance for formulating commit messages so that from now on when Claude does commits it knows to credit people properly. (Sorry, @eojthebrave 😭 — I got you on issue credit, though.)

nicxvan’s picture

nicxvan commented

Why does this commit list eojthebrave as the Drupal documentation maintainer?

As far as I can tell Drupal's Documentation maintainer position is still open: https://git.drupalcode.org/project/drupal/-/blob/main/core/MAINTAINERS.t...

I also searched the core queue and see no open issues to become the Drupal documentation maintainer.
- Source material: eojthebrave (Drupal documentation maintainer), issue #3581687

nicxvan’s picture

nicxvan commented

It would probably be more accurate to reference that eojthebrave is a founding member of the DWGO https://www.drupal.org/docs/working-group/documentation-working-group-ov... which @tim.plunkett pointed out to me.

webchick’s picture

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

Good call, are you able to whip up a patch?

nicxvan opened merge request !6

nicxvan’s picture

nicxvan commented

Created an MR, I'm still not sure this line is correct since it says eojthebrave is the source, but it seems that it was a discussion between the two of you and then Claude's interpretation.

Maybe the correct thing is to just remove that line entirely.
With git history you can see the issue number can't you?

Status: Fixed » Closed (fixed)

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