Use ReSpec to write technical documents

[sgort]

In GitLab by @datafluisteraar on May 11, 2022, 10:03

ReSpec makes it easier to write technical documents. It was originally designed for writing W3C specifications, but now supports many output formats.

In the Netherlands, Geonovum develops and manages standards for the use of geographic information in the public domain. Geonovum publishes a lot of documentation and has an 'HTML-first' publishing policy. They use the Respec open source environment. The use of Respec ensures that Geonovum's publications are largely digitally accessible (source).

Geonovum now has more than five years of experience with the use of Respec and has adapted the platform in such a way that it works well for its own organization. Thanks to Respec, Geonovum has been publishing digitally accessible information for several years now.

Other government organizations can also benefit from publishing in Respec. That is why Geonovum is working together with Logius and W3C to make Respec suitable for other government applications. For this they have divided Respec into a generic part and an organization-specific part. The generic part contains Respec's basic functions for publishing HTML documents. The organization-specific part can be configured to the corporate identity and publication locations of the organization.

for regels.overheid.nl we also want to use ReSpec and we are currently exploring this for LegitiMaat, a working method for conducting research by third parties into the use of algorithms by a government organization.

[sgort]

In GitLab by @datafluisteraar on May 11, 2022, 10:12

When trying out ReSpec in combination with GitLab and for an organization other than Geonovum, we come across puzzles and/or otherwise that we address here.

• Different logo specified in config.js doesn't scale with width & higth parameters?
• There's no gitlab parameter available in respecConfig. How to add?
• How to configure the name of the organization under the title and in the specStatus bar?
• How to configure previousPublishDate en previousMaturity?

[sgort]

In GitLab by @datafluisteraar on May 26, 2022, 15:25

Switched back to github for now. LegitiMaat publication expected to be on MinBZK github account.

Forked the Logius-standaarden/respec and started working on it. Progress can be followed in the applicable Pull Request.

[sgort]

NL profiel onderweg https://logius-standaarden.github.io/respec/

[sgort]

To do's:

• word docx als input/content
• conversie markdown
• publicatie mbv respec

[sgort]

Zie ook Logius-standaarden/respec#20

[sgort]

Wat voor nu relevant is voorlopig is een manier vinden om de snapshot van bijv. De LegitiMaat te kunnen publiceren op regels.overheid.nl, zonder menselijke tussenkomst ná generatie van die snapshot.

Daarvoor is al een issue #54. Deze kan naar de backlog.

[sgort]

Can be closed for now.