Restructure and normalize

marcvanandel commented 1 year ago

OK. Een grote PR .. die vooral heel veel raakt en inhoudelijk weinig écht wijzigt. Het is het voorstel voor een betere structuur + betere (bestands)naamgeving:

folders alleen 'lower case' en géén spaties
structuur:
- Home -> algemeen 'entry point' .. uitgebreid met een eerste leeswijzer
- Best practices -> verzameling van best practices
- Bronnen -> externe bronnen waar meer info is terug te vinden of overzichten
- Community -> onze OSPO-NL community zaken
- Nieuw project -> als je een nieuw project wilt starten, heb ik nodig ..
elke folder heeft een index.md .. die in de menu structuur niet wordt weergegeven .. maar direct wordt getoond als je op dat 'hoofdniveau' klikt
alle interne links 3x gecontroleerd en bijgewerkt .. hopelijk heb ik niks gemist 😆
LF line endings .. + vscode setting 💪 (index only has LF endings now)
logo in header + favicon 🎉

Looks neat, right? 😎

MauriceHendriks commented 1 year ago

In zijn algemeenheid:

De Over_ons pagina werkt niet meer.
In CONTRIBUTING mist bij de zin Geef het issue een passend label (zie verwachtingen. het afsluitende haakje.

MauriceHendriks commented 1 year ago

Nu we toch bezig zijn:

# find docs/ -type f -exec file {} \;
docs/assets/images/ospo-nl-logo-green.png: PNG image data, 1100 x 1100, 8-bit/color RGBA, non-interlaced
docs/assets/images/screenshot-kennisbank-OSPO-NL.png: PNG image data, 1191 x 474, 8-bit/color RGBA, non-interlaced
docs/best-practices/types-open-source-software-licenties.md: UTF-8 Unicode text
docs/best-practices/introductie-oss.md: UTF-8 Unicode text, with very long lines
docs/best-practices/GitHub.md: ASCII text, with very long lines
docs/best-practices/index.md: ASCII text
docs/best-practices/DCO.md: UTF-8 Unicode text
docs/best-practices/wetgeving.md: UTF-8 Unicode text
docs/best-practices/project-launch-checklist.md: UTF-8 Unicode text
docs/nieuw-project/PROJECT_GOVERNANCE.md: ASCII text
docs/nieuw-project/CODE_OF_CONDUCT.md: ASCII text
docs/nieuw-project/CONTRIBUTING.md: ASCII text
docs/nieuw-project/index.md: ASCII text
docs/bronnen/ondersteunende-organisaties.md: UTF-8 Unicode text
docs/bronnen/index.md: ASCII text
docs/bronnen/nederlands-overzicht.md: UTF-8 Unicode text
docs/README.md: ASCII text
docs/community/CONTRIBUTING.md: UTF-8 Unicode text
docs/community/CODE_OF_CONDUCT.md: UTF-8 Unicode text
docs/community/LICENSE.md: ASCII text
docs/community/over-ospo-nl.md: UTF-8 Unicode text
docs/community/SUPPORT.md: ASCII text
docs/community/index.md: ASCII text

Met name introductie-oss.md valt me op Ook zie ik een verschil tussen ASCII text en UTF-8 Unicode text

# find docs/ -type f -exec dos2unix -ih -- {} \;
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       1     190     247  no_bom    binary  docs/assets/images/ospo-nl-logo-green.png
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       3     206     181  no_bom    binary  docs/assets/images/screenshot-kennisbank-OSPO-NL.png
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0     108       0  no_bom    text    docs/best-practices/types-open-source-software-licenties.md
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0      53       0  no_bom    text    docs/best-practices/introductie-oss.md
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0      15       0  no_bom    text    docs/best-practices/GitHub.md
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0       3       0  no_bom    text    docs/best-practices/index.md
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0     104       0  no_bom    text    docs/best-practices/DCO.md
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0      50       0  no_bom    text    docs/best-practices/wetgeving.md
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0      81       0  no_bom    text    docs/best-practices/project-launch-checklist.md
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0      53       0  no_bom    text    docs/nieuw-project/PROJECT_GOVERNANCE.md
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0       9       0  no_bom    text    docs/nieuw-project/CODE_OF_CONDUCT.md
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0       6       0  no_bom    text    docs/nieuw-project/CONTRIBUTING.md
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0      11       0  no_bom    text    docs/nieuw-project/index.md
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0      54       0  no_bom    text    docs/bronnen/ondersteunende-organisaties.md
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0       6       0  no_bom    text    docs/bronnen/index.md
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0     106       0  no_bom    text    docs/bronnen/nederlands-overzicht.md
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0      22       0  no_bom    text    docs/README.md
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0     225       0  no_bom    text    docs/community/CONTRIBUTING.md
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0      72       0  no_bom    text    docs/community/CODE_OF_CONDUCT.md
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0       8       0  no_bom    text    docs/community/LICENSE.md
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0      26       0  no_bom    text    docs/community/over-ospo-nl.md
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0       8       0  no_bom    text    docs/community/SUPPORT.md
     DOS    UNIX     MAC  BOM       TXTBIN  FILE
       0       8       0  no_bom    text    docs/community/index.md

Hier geen problemen.

Verder is 120 toch te breed voor een half scherm 1920 pixel breed scherm. Zie voorbeeldje docs/best-practices/DCO.md:

Veel projecten vereisen tegenwoordig een DCO als juridische zekerheid over de bijdrage. Als ontwikkelaar of organisa
tie
teken je op dat moment o.a. voor dat de code die je bijdraagt een eigen creatie is, of compatible is met de licentie 
van
het projecten.

marcvanandel commented 1 year ago

Kijk. Da's nog 's een review! Loving it! ❤️

marcvanandel commented 1 year ago

@MauriceHendriks , beter zo?

MauriceHendriks commented 1 year ago

@MauriceHendriks , beter zo?

Jazeker. Dank!

Verder nog even een scan gedaan van loze spaties / tabs aan het einde van een regel:

# find . -type f -exec grep -nH -c '\\t\| $' {} \;
./best-practices/open-source-software-licenties.md:0
./best-practices/introductie-oss.md:3
./best-practices/GitHub.md:0
./best-practices/index.md:0
./best-practices/DCO.md:6
./best-practices/wetgeving.md:3
./best-practices/project-launch-checklist.md:0
./nieuw-project/PROJECT_GOVERNANCE.md:0
./nieuw-project/CODE_OF_CONDUCT.md:0
./nieuw-project/CONTRIBUTING.md:0
./nieuw-project/index.md:0
./bronnen/ondersteunende-organisaties.md:0
./bronnen/index.md:0
./bronnen/nederlands-overzicht.md:0
./README.md:1
./community/CONTRIBUTING.md:0
./community/CODE_OF_CONDUCT.md:0
./community/LICENSE.md:0
./community/over-ospo-nl.md:0
./community/SUPPORT.md:0
./community/PROJECT_GOVERNANCE.md:0
./community/index.md:0

Bijvoorbeeld in wetgeving.md:

-> hergebruikregels. 
+> hergebruikregels.

Overigens koste het me meer moeite dan ik van een OSPO kennisbank zou verwachten om de pagina's te draaien met run.sh.

marcvanandel commented 1 year ago

Top! Ook weer verbeterd ...

Wat betreft het draaien van de site lokaal .. is de README.md niet duidelijk (genoeg)? 🤔 Heb je suggesties hoe dat anders zou kunnen?

MauriceHendriks commented 1 year ago

Heb je suggesties hoe dat anders zou kunnen?

Er zitten een paar aannames in die README:

Dat men weet dat pip onderdeel is van Python.
Dat je de Python native package manager gebruikt.
In geval van het vorige punt je weet welke packages je nodig hebt.

Nu ken ik pip en Python wel, maar poetry nog niet. In mijn geval had ik dus nodig:

python3-poetry
python3-poetry-core
mkdocs
mkdocs-material
mkdocs-material-extensions

Soms is pip ook niet los geïnstalleerd, maar draai je pip zo:

python -m pip

Overigens heb ik lokaal de run.sh aangepast zodat hij ook van elders te benaderen is:

poetry run mkdocs serve -a 0.0.0.0:8000

Overigens kan je de header van een bash executable beter zo maken:

#/bin/env bash

Dan weet je zeker dat cross-platform bash gevonden wordt.

marcvanandel commented 1 year ago

Check. Beter zo? (zie laatste commit)

Volgens mij zou je alle mkdocs* dependencies automatisch moeten downloaden met poetry .. die niet per se met pip geïnstalleerd hoeft te worden.

Dat wij gekozen hebben voor mkdocs .. wat een Python stack is .. mag je zeker bevragen .. maar dat is wel wat het nu is. Suggesties zijn (uiteraard) welkom .. en tegelijk zijn er altijd alternatieven .. en hebben we 'gewoon' een keuze gemaakt 😄

MauriceHendriks commented 1 year ago

Volgens mij zou je alle mkdocs* dependencies automatisch moeten downloaden met poetry .. die niet per se met pip geïnstalleerd hoeft te worden.

Niet als de OS package manager gebruikt.

Volgens mij zou je alle mkdocs* dependencies automatisch moeten downloaden met poetry .. die niet per se met pip geïnstalleerd hoeft te worden.

Geen expliciete voorkeur voor het een of ander.

Check. Beter zo? (zie laatste commit)

Ik zou nog toevoegen dat wanneer je poetry and mkdocs via de package manager van (in dit geval Ubuntu) wil installeren je de packages nodigt hebt die ik heb genoemd.

marcvanandel commented 1 year ago

't Is wel een stuk beter geworden zo! 💪 Hopelijk vind je het zo goed genoeg .. en kan ik 'm gaan mergen? 😁

MauriceHendriks commented 1 year ago

@marcvanandel Je hebt ook @nicorikken gevraagd te reviewen, dus mergen kan sowieso nog niet.

ospo-nl / kennisbank

Restructure and normalize #66