Reviewcommentaar Bakker&Spees op concept uitwerking technische documentatie nov 2020

[ArneBruinse]

Hierbij onze review op het document:

Hoofdstuk 1:

Par 1.2:

• hier worden onderzoeksvragen gesteld, maar hierop wordt nergens in het rapport antwoord op gegeven
• Er is onderzocht wat maakt dat de implementatie als lastig wordt ervaren. Het lijkt mij zeer nuttig als dit ook gedeeld wordt, zodat we daar van kunnen leren. Dus wat exact maakt het implementeren lastig?
• Zelfde geldt voor de vraag die ze gingen onderzoeken waar de onduidelijkheden zitten. Dit zie ik ook niet terugkomen in het document.
• De vraag wie waarvoor verantwoordelijk is, wordt ook niet beantwoord.

Par 1.3:

• idem, dezelfde vragen zijn aangevuld, maar de antwoorden ontbreken. Het lijkt ons het beste dat er bij iedere vraag ook het gevonden antwoord gedeeld wordt.

• In hoofdstuk 2 staan wel bevindingen, maar die geven de indruk dat ze vooral gebaseerd zijn op eigen analyse van de documentatie. Dat hoort er natuurlijk ook bij, maar wel ter completering van wat er reeds in de interviews opgehaald is.

Hoofdstuk 2:

2.1.1 :

• Waarom zijn bijlage 2 en 3 niet benoemd? Vreemd dat ze hier ontbreken aangezien verderop wordt gezegd dat latere bijlagen zijn samengevoegd bij bijv 2 en 3.
• Waar staat dat de promotor sinds de 1.4 niet meer gebruikt wordt? Voor zover ik weet is het gebruik van de promotor nog steeds officieel onderdeel van de systematiek Bij de 1.6 release hoorde zelfs nog een reparatie uitleg van peter bonsma.

2.1.2:

• in het ober kok testprotocol staat toch uitgelegd wat je moet doen en wat er verwacht wordt? https://github.com/bimloket/visi/wiki/4.-Implementatie-a.d.h.v.-een-voorbeeld Dit lijkt ons niet ingewikkeld om te begrijpen. De uitleg waarom dit moeilijk te begrijpen is en wat er onduidelijk aan is ontbreekt ook. Dat het testprotocol niet aansluit bij het bouw domein is volgens mij gedaan om te voorkomen dat een nieuwe leverancier denkt dat ze gewoon dat ene raamwerk moeten ondersteunen en dat meteen duidelijk is dat je “vanalles” moet ondersteunen qua raamwerk. Daarnaast wil je zoveel mogelijk testcases achter elkaar hebben en niet teveel bulk die niets toevoegt. Dus als we een uav raamwerk gebruiken, heb je heel veel transacties, berichten en velden, waar de unieke cases dan tussen verstopt staan.

2.1.6:

• Er zijn veel meer standaarden in ontwikkeling in de sector, misschien goed om een totaalplaat te schetsen. En dan kun je ook meteen duidelijk aangeven hoe die in relatie staan tot elkaar. Een belangrijke vraag is of praktijkvoorbeelden nodig zijn- dan kom je weer meer op leverancier niveau en niet op het generieke abstracte systematiek niveau. Maar was het doel van deze opdracht alleen om ons te adviseren over de documentatie of het werkelijk zelfstandig verbeteren en completeren ervan?

2.3.1:

• Er wordt gesteld dat “lang niet al deze functionaliteiten worden gebruikt door de klanten”. Welke gaat het dan over? Dan graag een voorstel voor het verwijderen ervan als ze niet gebruikt worden. Functionaliteiten zijn in principe opgenomen om communicatie op contractvlak goed te kunnen ondersteunen. Zeker als Technia niet bevraagd is, kunnen de onderzoekers nooit een volledig beeld hebben wat er wel en niet gebruikt wordt.

• Waarom is het lastig om alle functionaliteiten te kunnen leveren? Daarnaast is ons beeld dat de functionaliteiten binnen de VISI-standaard benodigd om zijn correct (uniek) berichtenverkeer te kunnen borgen tussen organisaties. De vermelding dat gebruikers de scheidslijn tussen software functies en de systematiek niet herkennen, valt volgens ons ver buiten de scope van deze opdracht. Die gaat over de technische documentatie en niet over gebruikers die nooit de technische documentatie zullen lezen. Daarnaast zullen gebruikers altijd zelf aannames blijven maken over wat nu VISI is en wat software. Je zou dit hooguit als een andere documentatie / voorlichtingsvorm op kunnen pakken waarmee je in “jip-en janneke” taal uitlegt wat nu VISI systematiek is en wat niet. Pas daar wel bij op dat dit soort documentatie in de praktijk bijna nooit meer gelezen wordt door gebruikers.

2.3.2.:

• Als aanvulling op dat er geen duidelijke organisatiestructuur gevonden is door de onderzoekers, lijkt het ons goed dat hier ook benoemd wordt dat een duidelijk doel ook ontbreekt. Bijvoorbeeld: waar moet VISI in 2025 staan?. Wie is verantwoordelijk voor het promoten van de standaard en aan welke VISI-onderdelen worden gelden van het donateurschap besteed? Dit commentaar is natuurlijk enorm off-topic wat betreft dit rapport over de technische documentatie. Aangezien dit rapport daar zelf ook weinig de focus op houdt, lijkt het ons goed dit dan ook maar meteen even aan te kaarten, aangezien dat ook net zo goed van belang is voor potentiele nieuwe leveranciers.

Hoofdstuk 3:

3.1.1.1:

• Als er een voorstel is om het testprotocol te vervangen, dan is nog niet besloten dat er een nieuw testprotocol komt en het is ook nog niet gemaakt. Als er dan nu een situatie ontstaat waardoor het huidige testprotocol is weggestopt in “overige”, is de documentatie in mijn ogen minder duidelijk geworden in plaats van duidelijker. Dus een onacceptabele aanpassing.
• Bijlage 6 gaat over het metaraamwerk, als dat nu opgeknipt bij de normale raamwerk documentatie is gezet, vermoed ik dat het er alleen maar onduidelijker op wordt. Metaraamwerk is het enige raamwerk dat door de systematiek is vastgelegd hoe het er tot in detail uit moet zien en dus echt anders dan documentatie van het begrip raamwerk an sich. Lijkt ons ook niet de bedoeling.
• Nogmaals wordt hier gesteld dat de promotor is afgeschaft. Bij Bakker&Spees weten we daar niets vanaf. Ik heb meerdere mails van Paul Jansen, Peter Bonsma en Peter Willems over de 1.6 correctie van de promotor die B&S en Technia voor zover ik weet ook doorgevoerd hebben op dat moment.

3.1.2.2.

• Er wordt gesteld dat issues_template.md leesbaarder is gemaakt. Wij zien alleen opmaak aanpassingen, maar zien nog steeds onlogische dubbelingen waardoor dit niet snel en duidelijk in te vullen is tot een leesbaar totaal plaatje. Hebben de onderzoekers ook echt met hun in-house automatiseringskennis hiernaar gekeken?

3.2.1.1. -

• zoals eerder opgemerkt- waarom is het (restaurant) voorbeeld niet duidelijk? Het valt ons op dat er nogal veel stellingen gedaan worden waarvan wij de indruk krijgen dat er geen onderbouwing voor bestaat.

3.2.1.2:

• Volgens mij hebben de schrijvers van het document nog niet exact de systematiek begrepen, als ze voorstellen dat een veld in de raamwerk XML gevuld moet zijn. Dat kan alleen in een bericht XML. De XSD is een door de promotor gemaakt bestand, met al allerlei regels over een bericht opbouw. Dus dat werkt volgens mij gewoon goed. Daarnaast is dit dan een voorstel om de systematiek aan te passen in plaats van de documentatie, wat volgens mij de opdracht was. Het lijkt ons een vereiste dat mensen die de technische documentatie gaan herschrijven eerst moeten weten hoe die techniek werkt. 3.2.1.4:
• Volgens mij was dit juist een van de hoofddoel van deze opdracht: de hiaten in de huidige documentatie dichten. Hier heeft men denk ik geïdentificeerd dat het communicatieprotocol niet goed genoeg beschreven is, dus dat is dan toch juist wat onderzocht moet worden en gedocumenteerd? 3.2.2.3: -Is er onderzocht wie hiervoor verantwoordelijk is, zoals in paragraaf 1.2 gezegd wordt? Wij kennen alleen het puntensysteem, waarvan het inderdaad goed zou zijn als dit proces geformaliseerd zou worden. 3.3.1:
• Nogmaals staan hier meerdere adviezen over de ontwikkeling/aanpassing van de standaard, terwijl de opdracht toch was het verbeteren van de documentatie? Daarnaast zijn dit bekende wensen van Future insight, dus geen nieuw aangeleverde ideeën, geproduceerd door de opsteller van de concept uitwerking technische documentatie nov 2020.
• Het advies om de ontwikkeling af te remmen is volgens ons een risico dat de systematiek op termijn niet zal overleven. Een standaard die niet door ontwikkelt en nieuwe gebruikerswensen verwerkt zal op termijn zijn relevantie verliezen en afsterven.
• Er staat ook meerdere keren in dit document dat de VISI leveranciers de systematiek maar steeds door ontwikkelen. Dit doen wij wel in opdracht van het gebruikers comité. Het is valide om te kijken wat software is en wat systematiek, maar dat doen we altijd al zeer secuur in het Technisch Comité. Ik vraag me af of er nu onderdelen in de systematiek zitten die daar echt niet in thuis horen. Daarvan geven de schrijvers ook geen voorbeeld.
• Het opsplitsen van de systematiek is ook alweer een aanpassingsvoorstel voor de systematiek in plaats van de documentatie. Om toch maar op dit off-topic punt te reageren: Ook wij vinden het belangrijk dat de systematiek goed te implementeren is. Als dit betekent dat de systematiek in niveaus opgedeeld zou moeten worden, moet daar wel een plan voor komen. Dit brengt namelijk extra kosten voor de huidige leveranciers / visi donateurs en visi opdrachtgevers met zich mee. Die kosten moeten wel op de een of andere manier gedekt worden. Veel partijen zullen hun huidige raamwerken aan moeten passen of tools moeten creëren om hun raamwerken te downscalen voor bepaalde partijen. Verder moet er dan ook een strategie ontwikkeld worden hoe er gezorgd wordt dat dit de markt van VISI vergroot en er juist niet ingeteerd wordt op de huidige markt. Het imago van de systematiek kan eronder lijden als gebruikers VISI als minder effectief gaan ervaren ten opzichte van de huidige standaard. Vergeet ook niet dat de documentatie flink complexer gaat worden als je dit geheel in niveaus moet gaan opdelen en toch de samenhang begrijpelijk moet houden. Een dergelijk grove aanpassing moet daarom dan wel in een veel breder comité uitgewerkt worden waarin alle stakeholders meedenken en meewerken.

In het algemeen valt het op dat vooral informatie in een andere volgorde gezet is, in plaats van dat ontbrekende informatie is benoemd en toegevoegd. In onze verwachting zou dit het hoofddoel moeten zijn. We nemen aan dat een Future insight of andere leverancier met dezelfde informatie, maar in een andere structuur maar lichtelijk geholpen zou zijn bij de implementatie, want het is nog steeds dezelfde informatie. Om dan te adviseren om de systematiek scope te verkleinen lijkt ons in beginsel niet de juiste weg. Als eerste moet gewoon de documentatie dan toch volledig, begrijpelijk en overzichtelijk zijn?

Als ik snel door de nieuwe github heen loop zie ik dat bijvoorbeeld het testprotocol nu als een niet leesbare HTML file te vinden is onder “code”. Het lijkt mij een eerste vereiste dat je de beschikbare documentatie moet kunnen aanklikken en meteen lezen en niet dat je die eerst moet zien te saven en als losse file in je browser te openen ofzo. Alle afbeeldingen die tussen de tekst in stonden, staan nu los in een submapje. Dit lijkt ons een onacceptabele verslechtering van de documentatie

[ElisabethKloren]

Mijn informatie gekregen van de vorige product owner is dat de ondersteuning door BIM loket met een promotor sinds versie 1.4 niet meer ondersteund wordt, blijkbaar is met in kind bijdrage van de opsteller toch nog iets gebeurd voor versie 1.6. Dit zullen wij als beheerorganisatie moeten ophelderen.

[ArneBruinse]

Hoi @ElisabethKloren . Vreemd. Jouw voorganger, Paul Jansen(en een klein beetje Roy Voorend) heeft mij nog gewoon de correctie voor de 1.6 systematiek gemaild.

Verder is het volgens ons nooit met de Expert commissie gedeeld of besproken dat de promotor geen onderdeel van de systematiek meer uitmaakt. Zo is hier ook niets merkbaar van in de VISI Documentatie.

Kan en mag het BIM loket de standaard aanpassen zonder overleg met de expert commissie te plegen en dit te delen met de stakeholders?

Bij deze ook de mail van Paul, waaruit volgens mij blijkt dat het in de 1.6 nog ondersteund is door het crow/bimloket.

[ElisabethKloren]

@ArneBruinse je hebt helemaal gelijk, Jan-Pieter heeft dit verkeer onthouden en aan mij doorgegeven. Paul heeft ons gecorrigeerd en verwezen naar een heleboel mappen op de O-schijf van CROW omdat er wel een heleboel issues spelen rondom de promotor. Ik heb dus werk te doen om te zorgen dat ik de voor- en nadelen van die promotor opduikel; en wij moeten als expertcommissie aan de bak om te zorgen dat-ie dan ook nog werkt voor versie 1.7. Voor de technische documentatie heb ik een issue gemaaklt: #107

[ElisabethKloren]

Opdracht voltooid op 11-02-2021