Link to more information

MattWilcox commented 9 months ago

Description

Link back to the "Caching Element Queries" section of the docs, to give some context to the documentation.

Related issues

Me, whinging on Discord.

netlify[bot] commented 9 months ago

Deploy request for craft-docs rejected.

Name	Link
Latest commit	d2426f3fff6975f75484809f692a08de5b09d992

AugustMiller commented 9 months ago

Unfortunately, this patch will have to be made upstream in craftcms/cms, as this section of the page (and the equivalent Addresses, Assets, Categories, etc. element pages.) is generated automatically from the underlying PHP query classes.

Leaving this open as a reminder for myself!

Edit: to be clear—no action required from you. I will try and get it in for the next Craft release. 💞

MattWilcox commented 9 months ago

Out of interest, is there an orientation guide anywhere for people that might want to help contribute to the docs that covers things such as this, or any established methodology for the docs themselves?

AugustMiller commented 9 months ago

Frankly, I think the answer is no—we do not have public contribution guidelines. Internally, we have handbooks for the technical aspects of the documentation (what tools and processes are necessary to keep them up to date), as well as a writing style guide that governs all Pixel & Tonic output.

Some proposals, going forward:

[x] Alter the behavior of the footer in the documentation so that the edit link is deemphasized on pages that include generated/automated output (Done!);
[ ] Include a CONTRIBUTING.md file at the root of the repository like Craft does, with more explicit guidelines;
[ ] Make a succinct version of our style guide public, and link to it from the guidelines above;
[x] Externalize generated artifacts and use Vuepress’s importing functionality to make it more obvious what regions of pages are generated (In-Progress: #552);

I absolutely welcome any other recommendations! I don't think any of us realized how eager the community would be to contribute, so making this a smoother and more rewarding process is worth every bit of energy we can put into it. 💞

MattWilcox commented 9 months ago

Thanks! That's a solid list of stuff to help I think. I'll have a read of those and see if it makes sense to me. [edit: ah, CONTRIBUTING not done yet, got confused!]

AugustMiller commented 9 months ago

Converted the above into a to-do list so it's easier to track what's going on! ;)

AugustMiller commented 6 months ago

I've complete the process of splitting out generated artifacts from most pages, so I'm going to close this!

Pages like this no longer contain the substance of generated content—it's just included from a file in thedocs/.artifacts/ directory.

craftcms / docs