ictu/kwaliteitsaanpak

ICTU's Kwaliteitsaanpak: a set of guidelines for software development projects

ICTU Kwaliteitsaanpak Softwareontwikkeling

ICTU's Kwaliteitsaanpak is a set of guidelines used at ICTU for software development projects. It is only available in Dutch, sorry.

This repository contains the source information and automation scripts for generating ICTU's Kwaliteitsaanpak documentation. The Kwaliteitsaanpak itself is available via https://ictu.github.io/Kwaliteitsaanpak.

Documents

The Kwaliteitsaanpak consists of a main document containing the Kwaliteitsaanpak itself, a number of templates, and a self-assessment checklist. The sources are a collection of Markdown files and supporting material. Scripts convert the Kwaliteitsaanpak main document to html and pdf, the templates to docx, and the self-assessment checklist to xslx.

Authoring guidelines

• For each guideline:
  • Create a folder under ./Content/Maatregelen
  • Add 2 files to the folder
    • Definitie.md - brief one paragraph definition of the guideline
    • Maatregel.md - guideline title, description, and rationale
• Add the maatregel to the document structure definition in ./DocumentDefinitions/Kwaliteitsaanpak/ICTU-Kwaliteitsaanpak.md

Document definitions

• Each document definition is stored inside a subfolder of ./DocumentDefinitions
• A document definition is composed of a number of files:
  • document.json - meta data about the document
  • document.md - content of the document
  • document.css - styling
  • cover.css - styling
• Shared material such as headers, footers, and stylesheets are in the ./DocumentDefinitions/Shared folder

Generating the documentation

• Make sure you have Docker
• Clone this repository
• Run docker compose up
• Run open html/index.html to view the latest release and the work in progress (wip)

Releasing a new version of the documentation

1. Create a release branch: git checkout -b release-vx-y-z
2. Update the version number and release date in the change log in `./Content/Wijzigingsgeschiedenis.md``
3. Update the version number in docs/index.html
4. Create a new release folder in ./docs: mkdir docs/vx.y.z
5. Run VERSION=x.y.z docker compose up to generate the documents
6. Commit the changes and push to GitHub: git commit -a -m "Release vx.y.z"; git push
7. Review and merge the branch on GitHub
8. Tag the release and push the tag to GitHub: git checkout master; git pull -p; git tag vx.y.z; git push --tags

Point of contact

Points of contact for the ICTU Kwaliteitsaanpak Softwareontwikkeling and this repository are Auke Bloembergen and Frank Niessink.

kwaliteitsaanpak's Issues

Reformat change history in ICTU style

Woorden/termenlijst opnemen

• Afkortingen
• Definities
• Bronnen

De rol van de "sponsor" bij voorgestelde wijzigingen: klopt het dat die altijd zelf de wijziging ook uitvoert?

Stakeholder analyse als expliciete activiteit in de voorfase opnemen

In de voorfase expliciet de "Big Why" identificeren, documenteren en delen

Wijzigingsgeschiedenis opnemen

Scrum/scrum en verbindingen consequent spellen

Invulinstructie toevoegen aan assessment checklist

Vanuit het perspectief van het project dat de self-assessment doet. Dit toevoegen aan (de te maken) invulinstructie self-assessment.

TestX noemen als gesupport tool?

M10: Aanwezigen bij periodiek projectoverleg: ook projectleider?

Templates genereren vanuit KA

Beginnen met KP-template: opschonen, self-assessmentmaatregel opnemen in KP-template.

Word cloud has an extraneous line

Ook voorfase expliciet afsluiten, niet alleen realisatiefase (M27)

Zorgen dat je kunt zoeken met Ctrl-F in de pdf versie van de kwaliteitsaanpak

Dit heeft iets met fonts te maken: soms kan het build-script de google fonts niet downloaden en dan werkt het zoeken wel.

M19 hernoemen naar "Afgeschermde digitale omgeving"

Zoeken in de pdf op MacOS met "Voorvertoning" is niet betrouwbaar

Zoeken op bijvoorbeeld "sponsor" levert niet alle voorkomens van sponsor op in de zoekresultaten.

Inhoudsopgave genereren

Options:

• https://stackoverflow.com/questions/11948245/markdown-to-create-pages-and-table-of-contents
• https://github.com/jonschlinkert/markdown-toc

Datum op voorblad

Een aantal maatregelen (zoals M23 en M24) heeft nog geen beschrijving van hoe ICTU de maatregel invult

M13 hoort niet onder Projectorganisatie, maar onder Product

Nieuwe deliverable in de voorfase: aangepaste KA voor een project of verzameling projecten

Dit kan consequenties hebben voor het kwaliteitsplan(template).
Er moet dan ook een project-specifieke zelf-assessment checklist kunnen worden gemaakt.

Bijlage documenten voor maatregel M01 toevoegen

Headers bij volgende paragraaf houden in de pdf

Eerste onderzoek lijkt uit te wijzen dat niet (eenvoudig) kan.

Interne links fixen in pdf

Wordt lastig. Zie #16.

M07: te streng verwoord? Kan pas voldoen als product helemaal aan alle eisen voldoet?

Alleen performancetests zijn hier optioneel: deze er uit halen en zodanig benoemen.

M02: continu voldoen aan normen = mee bezig zijn genoeg?!

Interne links fixen in HTML

De links in HTML werken niet als de titel van een sectie op een haakje eindigt. Dat is dus makkelijk te fixen. Maar interne links in de pdf wordt lastig: geen van de html/markdown naar pdf converters lijkt dat te kunnen.

Bijlage met documenten voor Maatregel 1 heeft niet de goede boomstructuur

Verwijder de versie met alleen ICTU-aanvullingen bij maatregelen

Het build script genereert nu drie versies: een complete, een versie zonder ICTU-specifieke toevoegingen, en een versie met alleen de ICTU-specifeke toevoegingen. Die laatste is niet erg nuttig. @Barleduc Eens?

Diacrieten in de HTML versie werken niet goed

ICTU-specifieke SonarQube kwaliteitsprofielen verwijderen

M05 mist twee termen

M05 valt mij nu pas op:
​​Scrum team bestaand uit product owner, ontwikkelteam en Scrum master,
Proces met daily scrum, sprints, sprint planning, sprint review, sprint refinement,
Definition of Done,
Definition of Ready,
Product backlog.
Ik mis bij bullet 2 de retrospective en bij bullet 5 eventueel de sprint backlog

Wider margins

As long as we don't have two columns, have wider margins so that finding the start of the next line is easier.

M01 op te leveren producten => niet perse door ICTU (feedback Wigle)

Introductie uit 1.0 versie weer toevoegen

Maatregel mbt ISO 25010 niet duidelijk

Expliciet de afhankelijkheden tussen de producten uit de voorfase beschrijven

docker-compose up fails with ERROR 403: Forbidden when trying to download phantomjs

--2018-01-23 14:45:08-- https://bitbucket.org/ariya/phantomjs/downloads/phantomjs-1.9.7-linux-x86_64.tar.bz2
Connecting to bitbucket.org (bitbucket.org)|104.192.143.2|:443... connected.
HTTP request sent, awaiting response... 302 Found
Location: https://bbuseruploads.s3.amazonaws.com/ariya/phantomjs/downloads/phantomjs-1.9.7-linux-x86_64.tar.bz2?Signature=6XIOsFf3Zvl2Dzion11uAhg%2BCjc%3D&Expires=1516720317&AWSAccessKeyId=AKIAIQWXW6WLXMB5QZAQ&versionId=null&response-content-disposition=attachment%3B%20filename%3D%22phantomjs-1.9.7-linux-x86_64.tar.bz2%22 [following]
converted 'https://bbuseruploads.s3.amazonaws.com/ariya/phantomjs/downloads/phantomjs-1.9.7-linux-x86_64.tar.bz2?Signature=6XIOsFf3Zvl2Dzion11uAhg%2BCjc%3D&Expires=1516720317&AWSAccessKeyId=AKIAIQWXW6WLXMB5QZAQ&versionId=null&response-content-disposition=attachment%3B%20filename%3D%22phantomjs-1.9.7-linux-x86_64.tar.bz2%22' (ANSI_X3.4-1968) -> 'https://bbuseruploads.s3.amazonaws.com/ariya/phantomjs/downloads/phantomjs-1.9.7-linux-x86_64.tar.bz2?Signature=6XIOsFf3Zvl2Dzion11uAhg+Cjc=&Expires=1516720317&AWSAccessKeyId=AKIAIQWXW6WLXMB5QZAQ&versionId=null&response-content-disposition=attachment; filename="phantomjs-1.9.7-linux-x86_64.tar.bz2"' (UTF-8)
--2018-01-23 14:45:08-- https://bbuseruploads.s3.amazonaws.com/ariya/phantomjs/downloads/phantomjs-1.9.7-linux-x86_64.tar.bz2?Signature=6XIOsFf3Zvl2Dzion11uAhg+Cjc=&Expires=1516720317&AWSAccessKeyId=AKIAIQWXW6WLXMB5QZAQ&versionId=null&response-content-disposition=attachment;%20filename=%22phantomjs-1.9.7-linux-x86_64.tar.bz2%22
Connecting to bbuseruploads.s3.amazonaws.com (bbuseruploads.s3.amazonaws.com)|52.216.129.131|:443... connected.
HTTP request sent, awaiting response... 403 Forbidden
2018-01-23 14:45:09 ERROR 403: Forbidden.

M26 - Waarom moet de projectenorganisatie deze expertise op afroep beschikbaar hebben en waarom moeten projecten er gebruik van maken?

Hier loopt de implementatie bij ICTU door de generieke maatregel. De boodschap is: doe regelmatig onafhankelijke security tests.

Bijlage met risico's en maatregelen weer toevoegen

Self-assessment als maatregel in de kwaliteitsaanpak en het kwaliteitsplantemplate opnemen

• Maatregel in KA
• Self-assessment spreadsheet/checklist genereren
• Opnemen in kwaliteitsplantemplate

Checken dat het juiste jaartal van de BIR wordt gebruikt (moet 2017 zijn)

Scrumcoach beschrijving in KA aanpassen

Don't use all capitals for emphasis

Titel van maatregelen verwijderen uit foldernamen tbv onderhoud

Nieuwe maatregel: projectspecifieke risicoanalyse?

M25 opnemen in M01?

De normen van de metrieken uit HQ zitten niet in de kwaliteitsaanpak: toevoegen?

Maatregelen in de assessment checklist zelfde volgorde/ordening geven als in KA

• Indicatie toevoegen van het soort (project/afdeling) maatregel
• Volgorde aanpassen
• Paragraafstructuur overnemen

Zorgen dat gegenereerde versie van kwaliteitsaanpak "publicatie-ready" is voor ICTU-website

• Specs opvragen bij afd. communicatie.
• Hoofdstuknummers
• Headers bij volgende paragraaf houden