Proposal: Dynamic documentation & automated UI screenshots

[Simone Nardi]

Hi,

I'd like to propose an improvement for managing our platform's user tutorials, leveraging tools and dependencies we already have in the codebase via a Docs-as-Code workflow:

• Wiki Generation with MkDocs (Material):

  Create a dedicated folder for user tutorials (e.g., /wiki or /docs/wiki) with Markdown files. The wiki would be compiled automatically on every build or release.

• Automated UI Screenshots via Playwright:

  Integrate pytest-playwright into our existing test suite (pytest-django). During End-to-End test runs, the script navigates key application pages, automatically captures updated UI screenshots, and saves them directly to the tutorial image directory.

Benefits for the project:

• Zero manual image maintenance: If a view or form changes, re-running the tests automatically updates the screenshots in the guide.

• Guaranteed alignment: Documentation evolves in sync with software development and Pull Requests.

• Minimal setup impact: We leverage pytest-django, which is already present. The only additional packages needed would be mkdocs-material and pytest-playwright.

What do you think?

Simone

[Donald Dale Milne]

    Interesting, especially the ability to automatically capture updated UI screenshots.  Updated visual examples of procedural changes would be useful.  Updating these examples of procedure is only a small part of the wiki, however.  It does not (and very likely cannot) address the major breakdown in updating our wiki of rules and procedures.  Every time the Policy group or the Board updates a rule or procedure, we currently manually transcribe the vote to the appropriate location in the wiki.  We also revise any conflicts and often need to locate and change multiple references to the use of the rule which was changed.  Sometimes, of course, we miss locations that should be changed.  These changes currently require a volunteer to make the changes and we have a committee of three (Documentation Coordinators) who perform this function.  Updates are routinely at least several votes behind.

    Unfortunately, I doubt that such updates can be performed by automation.

- Don

--
You received this message because you are subscribed to the Google Groups "gcd-tech" group.
To unsubscribe from this group and stop receiving emails from it, send an email to gcd-tech+u...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/gcd-tech/137d9261-7a5a-4f82-b31c-aec2db11be68n%40googlegroups.com.

[Jochen G.]

We have at least two documentation needs.

Rules and guidelines, which follow votes and discussion.

How to actually index and enter data, in form of tutorials or videos.

This addresses the second, which we are lacking, or what we have is
outdated or not regularly updated.

Not idea how good this would work, but definitely worth a try.

Jochen

Am 30.09.26 um 00:38 schrieb 'Donald Dale Milne' via gcd-tech:

>     Interesting, especially the ability to automatically capture
> updated UI screenshots.  Updated visual examples of procedural changes
> would be useful.  Updating these examples of procedure is only a small
> part of the wiki, however.  It does not (and very likely cannot) address
> the major breakdown in updating our wiki of rules and procedures.  Every
> time the Policy group or the Board updates a rule or procedure, we
> currently manually transcribe the vote to the appropriate location in
> the wiki.  We also revise any conflicts and often need to locate and
> change multiple references to the use of the rule which was changed.
> Sometimes, of course, we miss locations that should be changed.  These
> changes currently require a volunteer to make the changes and we have a
> committee of three (Documentation Coordinators) who perform this
> function. Updates are routinely at least several votes behind.
>
>     Unfortunately, I doubt that such updates can be performed by
> automation.
>
> - Don
>
> On 9/29/2026 9:57 AM, Simone Nardi wrote:
>>
>> Hi,
>>
>> I'd like to propose an improvement for managing our platform's user
>> tutorials, leveraging tools and dependencies we already have in the
>> codebase via a Docs-as-Code workflow:
>>

>> *
>>
>> *Wiki Generation with MkDocs (Material):*

>>
>> Create a dedicated folder for user tutorials (e.g., /wiki or /
>> docs/wiki) with Markdown files. The wiki would be compiled
>> automatically on every build or release.
>>

>> *
>>
>> *Automated UI Screenshots via Playwright:*

>>
>> Integrate pytest-playwright into our existing test suite (pytest-
>> django). During End-to-End test runs, the script navigates key
>> application pages, automatically captures updated UI screenshots,
>> and saves them directly to the tutorial image directory.
>>

>> *Benefits for the project:*
>>
>> *
>>
>> *Zero manual image maintenance:* If a view or form changes, re-

>> running the tests automatically updates the screenshots in the guide.
>>

>> *
>>
>> *Guaranteed alignment:* Documentation evolves in sync with

>> software development and Pull Requests.
>>

>> *
>>
>> *Minimal setup impact:* We leverage pytest-django, which is

>> already present. The only additional packages needed would be
>> mkdocs-material and pytest-playwright.
>>
>> What do you think?
>>
>> Simone
>>
>> --
>> You received this message because you are subscribed to the Google
>> Groups "gcd-tech" group.
>> To unsubscribe from this group and stop receiving emails from it, send
>> an email to gcd-tech+u...@googlegroups.com.
>> To view this discussion visit https://groups.google.com/d/msgid/gcd-
>> tech/137d9261-7a5a-4f82-b31c-aec2db11be68n%40googlegroups.com

>> <https://groups.google.com/d/msgid/gcd-tech/137d9261-7a5a-4f82-b31c-
>> aec2db11be68n%40googlegroups.com?utm_medium=email&utm_source=footer>.

>
> --
> You received this message because you are subscribed to the Google
> Groups "gcd-tech" group.
> To unsubscribe from this group and stop receiving emails from it, send

> an email to gcd-tech+u...@googlegroups.com <mailto:gcd-
> tech+uns...@googlegroups.com>.

> To view this discussion visit https://groups.google.com/d/msgid/gcd-

> tech/74ae565d-6665-47d9-aab3-6ec36c8be3e6%40att.net <https://
> groups.google.com/d/msgid/gcd-tech/74ae565d-6665-47d9-
> aab3-6ec36c8be3e6%40att.net?utm_medium=email&utm_source=footer>.