Loading service/documentation.md +19 −6 Original line number Diff line number Diff line Loading @@ -317,6 +317,25 @@ people review changes done to it. As [Jacob Kaplan-Moss quipped](https://jacobia In other words, we'd need a technical writer to review our docs, or at least setup a self-editing process the way Kaplan-Moss suggests above. ### Templating The current "service template" has one major flaw: when it is updated, the editor needs to manually go through *all* services and update those. It's hard to keep track of which service has the right headings (and is up to date with the template). One thing that would be nice would be to have a way to keep the service pages in sync with the template. I [asked for suggestions in the Hugo forum](https://discourse.gohugo.io/t/using-and-maintaining-markdown-templates/31020), where a simple suggestion was to version the template and add that to the instances, so that we can quickly see when a dependency needs to be updated. To do a more complete comparison between templates and instances, I suspect I will have to roll my own, maybe something like [mdsaw](https://gitlab.com/hydrargyrum/mdsaw) but using a real parse tree. See also [scaraplate](https://scaraplate.readthedocs.io/) and [cookiecutter](https://cookiecutter.readthedocs.io/). ## Goals Note: considering we *just* migrated from ikiwiki to GitLab wikis, it Loading Loading @@ -417,11 +436,5 @@ GitLab wikis. See also [this LWN article](https://lwn.net/Articles/822969/). One thing that would be nice would be to have a way to keep the service pages in sync with the template. I [asked for suggestions in the Hugo forum](https://discourse.gohugo.io/t/using-and-maintaining-markdown-templates/31020) but I suspect I will have to roll my own, maybe something like [mdsaw](https://gitlab.com/hydrargyrum/mdsaw) but using a real parse tree. See also [scaraplate](https://scaraplate.readthedocs.io/) and [cookiecutter](https://cookiecutter.readthedocs.io/). [vale]: https://errata-ai.gitbook.io/vale/ [markdownlint]: https://github.com/DavidAnson/markdownlint Loading
service/documentation.md +19 −6 Original line number Diff line number Diff line Loading @@ -317,6 +317,25 @@ people review changes done to it. As [Jacob Kaplan-Moss quipped](https://jacobia In other words, we'd need a technical writer to review our docs, or at least setup a self-editing process the way Kaplan-Moss suggests above. ### Templating The current "service template" has one major flaw: when it is updated, the editor needs to manually go through *all* services and update those. It's hard to keep track of which service has the right headings (and is up to date with the template). One thing that would be nice would be to have a way to keep the service pages in sync with the template. I [asked for suggestions in the Hugo forum](https://discourse.gohugo.io/t/using-and-maintaining-markdown-templates/31020), where a simple suggestion was to version the template and add that to the instances, so that we can quickly see when a dependency needs to be updated. To do a more complete comparison between templates and instances, I suspect I will have to roll my own, maybe something like [mdsaw](https://gitlab.com/hydrargyrum/mdsaw) but using a real parse tree. See also [scaraplate](https://scaraplate.readthedocs.io/) and [cookiecutter](https://cookiecutter.readthedocs.io/). ## Goals Note: considering we *just* migrated from ikiwiki to GitLab wikis, it Loading Loading @@ -417,11 +436,5 @@ GitLab wikis. See also [this LWN article](https://lwn.net/Articles/822969/). One thing that would be nice would be to have a way to keep the service pages in sync with the template. I [asked for suggestions in the Hugo forum](https://discourse.gohugo.io/t/using-and-maintaining-markdown-templates/31020) but I suspect I will have to roll my own, maybe something like [mdsaw](https://gitlab.com/hydrargyrum/mdsaw) but using a real parse tree. See also [scaraplate](https://scaraplate.readthedocs.io/) and [cookiecutter](https://cookiecutter.readthedocs.io/). [vale]: https://errata-ai.gitbook.io/vale/ [markdownlint]: https://github.com/DavidAnson/markdownlint