Is there a use case for an mkdocs-based solution separate from the govuk-eventy-plugin?

[SoumayaMauthoorMOJ]

There is a community-managed eleventy plugin for creating technical documentation with a gov.uk design:
https://github.com/x-govuk/govuk-eleventy-plugin

This uses the govuk front-end and various other govuk artefacts which means it's more likely to meet accessibility standards and easier to keep up with gov.uk design standards.

On the other hand:

• Eleventy does not currently have support for extracting python doctrings and publishing jupyter notebooks
• pure-python projects would now have a node.js dependency for publishing documentation
• Mkdocs plugins are written in python and easier to customise for python-based teams
• Mkdocs materials comes pre-packaged with a lot of nifty features e.g. dark mode

Should we maintain a mkdocs-based documentation tool separate from the eleventy plugin or should we use the eleventy plugin and build custom tools to support pythonic and/or analytical requirements?

[michalc]

I do like mkdocs-tech-docs-template, and have used it for a few projects, and have now briefly tried https://github.com/x-govuk/govuk-eleventy-plugin for one project

This uses the govuk front-end and various other govuk artefacts which means it's more likely to meet Accessibility standards and easier to keep up with gov.uk design standards

But... as it stands, I do think the gov uk eleventy plugin is better, exactly for this reason. mkdocs-tech-docs-template is built on Material Design, so I do now fear there will be long term pain trying to bolt on bits of the GOV.UK design system - sort-of-but-never-quite-matching, both purely aesthetically and in terms of visual and non-visual accessibility.

There is a downside as you say...

However it does not currently have support for extracting python doctrings and publishing jupyter notebooks.

But my instinct is that avoiding this downside isn't worth it. Perhaps if this project were to move away from being based on Material Design and being raw mkdocs + the GOV.UK design system, then this project may be better for a lot of cases.

I also suspect there must be a way of extracting python docstrings and publishing jupyter notebooks from eleventy. Admittedly I haven't tried to, but I think for my purposes, even if it is essentially impossible within any reasonable amount of time, I would just... not do that, but still use eleventy for docs. Or at worse, extract things manually and incorporate them into docs just as raw HTML - which from brief testing is supported by eleventy.

Should we maintain a mkdocs-based documentation tool separate from the eleventy plugin or should we use the eleventy plugin and build custom tools to support pythonic and/or analytical requirements?

In summary... I think using eleventy and exploring how to integrate any custom bits is probably the easiest way to get nice documentation that's consistent with the GOV.UK design system. If really Javascript has to be avoided - then I think the alternative long term plan would be to move this project to just being built on raw mkdocs without the material design bit - an mkdocs port of the eleventy plugin if you will. But - this is probably a fair amount of work. Maybe to only be started if it does look end up especially tricky to do the Python bits from eleventy?

[gwionap]

I think it's still useful to have govuk-mkdocs-material (using its new name) for use in pure python based projects e.g. if you're developing a new library. Granted this is subjective, but it feels like more and more python based projects are moving to adopting mkdocs material as their tool of choice (iceberg python library is the latest I've seen switch over). From a user / analyst perspective, it's much easier for me to pick up and use govuk-mkdocs-material because it doesn't require me to learn anything new. Also, from a platform perspective, tools can often be limited for analysts and so installing a node library might not be something that's possible.

[Thomas-Hirsch]

I'm a little in two minds here. One the one hand, the advantages of our mkdocs package over eleventy (particularly for tech docs authors) are pretty substantial as Gwion and Soumaya have outlined. I think if your main focus is on writing documentation, rather than making A Website, mkdocs is pretty clearly superior. On the other, the limited alignment with the Gov.uk design system does make me concerned that it would always be considered a second-class system in the Gov.uk ecosystem. (not to mention relevant xkcd)

[SoumayaMauthoorMOJ]

I think there's a few questions we need to answer:

• Does data engineering have the resources to support an mkdocs-based solution?
• Can MOJ analysts with a locked-down laptop install node libraries?
• Is there a need for MOJ analysts to create static websites that have the govuk design? For example ap-tools-training doesn't have a govuk design.
• Would the team behind govcookiecutter be happy to use a node.js documentation tool?
• Is govuk-mkdocs-material (using its new name) compatible with R?
• Could the mkdocs-based solution be used for analytical projects? As stated by the creator of deprecated govukhugo package here:

GOV.UK was developed largely for the purpose of replacing a large number of websites providing information and transactional services to the public and businesses. As a result the design system’s main layouts and components are tailored towards the presentation of long-form text (e.g. news releases, policy papers, guidance documents) and forms (e.g. applications for licenses, provision of tax returns and information for regulatory compliance), it was not designed with the presentation of data and statistics in mind. The GOV.UK design system does not support specialist components for data-heavy needs. For example most charts in GOV.UK documents are included as static raster images rather than with accessible web technologies such as SVG, and data tables cannot be sorted. ↩︎

[SoumayaMauthoorMOJ]

Actions:

• @hrahim-moj to come up with user stories to clarify use cases where mkdocs-based solution could be relevant
• @tom-webber to test whether eleventy plugin is compatible with Analytical Platform and whether Apps/projects could use it for documentation

[tom-webber]

After a test and ask around for alternatives, it seems we'd be unable to view eleventy plugin previews on the AP's JupyterLab because we don't allow SSH, meaning we have no way of reaching localhost:8080 of the JupyterLab container.

As it stands, I'm also currently unable to install the plugin due to some node and npm version incompatibilties. This could be updated through updating the base image, but it might be a slow process.

[SoumayaMauthoorMOJ]

Hi @tom-webber really appreciate you looking into this! Do you know if this means we'd be unable to preview the mkdocs documentation as well since it also useslocalhost:8080 (see https://www.mkdocs.org/getting-started/)

[tom-webber]

Yes it does. After some discussion with the team, I'm going to put some time into looking for another solution for making these available on AP.

[hrahim-moj]

Soumaya and I came up with the following user story to encapsulate what the use case for this MkDocs in the current Gov documentation landscape:

As a Python-based project team member
I want to write our documentation using Python
So that I do not need to install non-python dependencies on my machine, which takes extra time, and might have permission restrictions

All things considered, it's not significant enough to warrant its adoption. MkDocs could coexist alongside the Eleventy Plugin (since Eleventy seems to be able to host information 'portals' rather than purely docs), but only if it replaced the Tech Docs Template, which is still supported for the time being.