Documenteren, waarom en hoe? -2

Dit is het tweede deel van twee blogs over documenteren, voor het eerste blog, zie deze link.

Bovenstaand ziet u een standaard dashboard gebaseerd op de dataset Superstore. Aan de hand van dit dashboard zijn een aantal onderstaande documentatievoorbeelden gemaakt. Helemaal onderaan dit blog ziet u een korte vergelijking tussen de methodes. Het verschilt per situatie wat het beste voor u zou werken.

_________________________________

Voorbeeld 1

Het eerste voorbeeld is zeer summier

1. User story / Einddoel
   • Bij het bedrijf Superstore wil men een dashboard waarbij de verkoop op verschillende onderdelen getoond moet worden. Er zijn (nog) geen KPI’s, maar … (kort en krachtig).
2. Wensen / Randvoorwaarden / Acceptance criteria
   • Het dashboard moet weergeven hoeveel kantoorartikelen en machines er werden verkocht in de afgelopen [x] jaren en in welke staten. Daarnaast willen de opdrahtgeve
   • De opdrachtgevers zijn dhr. Taft en mevr. Roosevelt van de afdeling ….
   • De gebruikers zijn …
   • Het dashboard moet in de huisstijl van … (enz.)
3. Feiten
   • Het dashboard moet uiteindelijk gepubliceerd worden op Tableau Server op de site …;
   • Het datumveld waarop de assen/waarden m.b.t. tijd gebaseerd zijn is [Order Date];
   • De waarden worden volluit maar zonder komma weergegeven als het gaat om aantallen;
   • De waarden voor valuta worden als volgt geschreven (in US dollars) als…. (enz.);
4. Bronnen
   • Voor nu is de data te vinden in een Excel-matrix met de naam … in map …
   • In de toekomst moet het dashboard gekoppeld zijn aan de published datasource ….
5. Dashboards
   • Het workbook bestaat uit één dashboard dat uit vier worksheets (zie 6) en een balk met filters, parameters;
   • Het dashboard beantwoord de volgende vragen:
6. Worksheets
   1. Staafdiagram (in het workbook onder de naam ‘Bar Chart‘);
   2. Lijndiagram (Line Chart);
   3. Kaart (Map);
   4. LOD – Acquisitie (LOD – Acquisition).
7. Overige gegevens
   • (Hier zou u informatie over de eigenaar van het dashboard en de databron kunnen plaatsen. Dit is op zich wel goed om te noteren zodat duidelijk is bij wie de gebruiker moet zijn als de data niet klopt of als het dashboard niet meer werkt.)

---

Voorbeeld 2

Het tweede voorbeeld is een uitgebreide documentatie.

1. User story
   • (Zie voorgaand).
2. Wensen / Randvoorwaarden / Acceptance criteria
   • (Zie voorgaand).
3. Feiten
   • (Zie voorgaand).
4. Bronnen
   • (Zie voorgaand).
5. Dashboards

1. Filters en parameters (zie onderstaand en 6. Worksheets, 7. Calculaties en 8. Parameters);
2. Staafdiagram (zie 6.1.)
3. Kaart (zie 6.2.)
4. LOD – Acquisitie (6.3)
5. Lijndiagram (6.4)

Filters:

• ‘Staat’ gebaseerd op [State] (discrete dimension string);
• ‘Sub-Categorie’ op

Parameters:

• Datumeenheid of Date Part gebaseerd op parameter P_Date Part (zie 8.1) en calculatie C_Date as String (zie 7.1).

Aanvullende informatie
De worksheets Staafdiagram (2 / 6.1) en Kaart (3 / 6.2) werken als filters voor het gehele dashboard.

De instellingen voor het actiefilter zijn als volgt:

De worksheets ‘Staafdiagram’ (Bar Chart) en ‘Kaart’ (Map) functioneren als filter. Ze zijn automatisch aangemaakt door de trechter aan te zetten die rechts van het worksheet in het dashboard verschijnt als er op geklikt wordt. Deze filter-acties kunnen ook aangemaakt worden via het actie-menu (via ‘ Add Action’ met de instellingen uit de rechter afbeelding). De instellingen zijn Bar Chart (of Map) als enige Source Sheet en alle andere aanwezige worksheets als Target Sheets. Het filter staat op ‘All fields’ , Run action on : Select en Clearing the selection will : Show all values.

6. Worksheets

(Hier kunt u een inleiding plaatsen)

NB In dit voorbeeld ga ik gelijk naar worksheet 6.4 omdat dit een LOD bevat.

6.4 LOD – Acquisition

Columns: [C_Date as string], discrete dimension string, zie 7.1.
Rows: SUM([Sales]) / TOTAL(SUM([Sales])), continuous measure integer als table calculation met de volgende instellingen: Percent of Total, richting: Table down zie 7.2.;
Filters: (Alleen maar Action Filters gebaseerd op andere worksheets, zie hoofdstuk 5)
Marks: DATEPART(‘year’, [C_LOD Acquisition Date]) op Colour.

(Etc.)

Voor de LOD, zie hoofdstuk 7.2 (C_LOD Acquisition Date).

7. Calculaties

1. C_Date as String:

IF [P_Date Part] = “Week” THEN “W”+” “+ str(ISOWEEK([Order Date]))+ ” ‘” +
right(str(DATEPART(“year”,[Order Date])),2)
ELSEIF [P_Date Part] = “Month” THEN LEFT(DATENAME(‘month’,[Order Date]),3) +” ‘” +
right(str(DATEPART(“year”,[Order Date])),2)
ELSEIF [P_Date Part] = “Quarter” THEN “K” + STR(DATEPART(‘quarter’,[Order Date])) +” ‘” +
right(str(DATEPART(“year”,[Order Date])),2)
ELSEIF [P_Date Part] = “Year” THEN STR(DATEPART(“year”,[Order Date]))
END

Toelichting: om te kunnen schakelen tussen via verschillende dateparts/datumeenheden zoals week en maand is het veld (date)

2. C_LOD Acquisition Date:

{FIXED [Customer ID] : MIN([Order Date])}

Toelichting: Door de informatie/view vast te pinnen op Customer ID is dat de enige dimensie waarnaar gekeken wordt. Vervolgens wordt de minimale datum per Customer ID, oftewel het eerste moment waarop een klant voorkomt in de database.

(NB zie ook hier onder 1.)

NB Soms is het handig bij geneste calculaties om het op de volgende manier te doen

1. IF RANK(SUM([Sales])) <= [P_1. Top N] THEN [C_4. Customised Sales] enz….
   • ↳ 4. Customised Sales: IF [Category] = ‘Cardboard’ THEN SUM([Sales])*0,8 ELSE enz…

(Calculatie is afkomstig uit dit blog)

Oftewel: de delen van de calculatie kleuren, calculaties en parameters nummeren (en van de prefix C_ of P_ voorzien) en verwijzen naar calculaties onder de geneste. (Het is dan wel de vraag of de calculatie dan verderop in de lijst nogmaals genoemd moet worden of dat een tekst ‘zie calculatie 1 (naam)’ volstaat.

8. Parameters

(Wederom kan hier eventueel een inleiding)

8.1 P_Date Part:

• Data type: String;
• Current value: ‘ Maand’
• Value when workbook opens: Current value
• Allowable values: List
  • Value: Week = Display As : Week
  • enz.
• Fixed

(Voor het gemak gebruik ik meestal een screenshot van parameter, dat scheelt het nodige typewerk en het kan in tegenstelling tot calculaties/calculated field toch niet gekopieerd en geplakt worden (helaas)).

---

Een derde weg?

Een tussenoplossing zou wellicht het beste zijn, maar is het lastigste weer te geven. Aangezien ik het persoonlijk altijd lastig vind om te bepalen wat belangrijk genoeg is om toch tot in detail te behandelen of over te laten aan de gebruiker.

1. User story
   • (Zie voorgaand).
2. Wensen / Randvoorwaarden / Acceptance criteria
   • (Zie voorgaand).
3. Feiten
   • (Zie voorgaand).
4. Bronnen
   • (Zie voorgaand).
5. Dashboards
   • Zoals onder ‘2 Uitgebreid’.
6. Worksheets
   • Staafdiagram (in het workbook onder de naam ‘Bar Chart‘);
   • Lijndiagram (Line Chart);
   • Kaart (Map);
   • LOD – Acquisitie (LOD – Acquisition).
7. Calculaties
   • De calculaties slecht noemen en niet voluit uitschrijven.

---

Beoordeling

Alle drie de manieren van documenteren hebben hun voor- en nadelen, hieronder een kleine vergelijking:

Een blog over het documenteren in Alteryx volgt nog.