Wanneer je surft naar github.com/provinciesincijfers kom je op de interprovinciale Github pagina terecht. Hier vind je verschillende repositories; dit zijn verschillende ruimtes binnen de /provinciesincijfers ruimte. Een beetje zoals de kanalen binnen de Interprovinciale Teamsomgeving. Zo heb je bv PinC-taakopvolging, waar de issuetracker zich bevindt en JiveDocumentation, waar alle praktische afspraken staan.
- Klik op JiveDocumentation.
- Nu kom je automatisch in het tabblad <> Code terecht. Hier bevinden zich alle documenten. Naast <> Code, staat de tab 'Issues', waar je problemen kan signaleren.
- Binnen <> Code zie je eerst 12 verschillende mappen die de opdeling van alle praktische afspraken volgen.
- Wanneer je naar onder scrollt, komt je op het overzichtsdocument terecht (JiveDocumenattion – Start to Swing). Dit is in Markdown (.md) formaat, zodat het automatisch rechtstreeks getoond wordt binnen Github.
- De onderdelen 'Basisinfrastructuur', 'Basisonderdelen beheer' en 'Basisafspraken beheer Swing' staan rechtstreeks in dit overzichtsdocument. Vanaf 'Beheer in Swing Studio' staat alles in de bijhorende mappen. Het overzichtsdocument beschrijft enkel de inhoud van deze mappen.
- Wanneer je doorklikt naar een map, zie je de verschillende bestanden opgelijst. Hier kan je gewoon op klikken. Onderaan staat een beschrijving van de inhoud van de map. Dit is de README.file (hieronder meer daarover).
Je kan op verschillende manieren zoeken binnen JiveDocumentation
- Klik rechtstreeks door naar de juiste map en document.
- Scroll naar onder in het overzichtsdocument (JiveDocumentation – Start to Swing) en kijk waar je bestand staat.
- Nog makkelijker: via de zoekfunctie. Dit kan op 2 manieren:
-
(1): Klik links bovenaan in de zoekbalk en typ een sleutelwoord in. In de opties die daaronder verschijnen, kan je ervoor kiezen om binnen de repository te zoeken waarin je zit (in dit geval: JiveDocumentation), te zoeken binnen de organisatie (in dit geval: Provinciesincijfers), of in heel Github. Kies de eerste optie. Vervolgens zie je de zoekresultaten.
-
(2): Zoeken op bestandsnaam. Dit kan via de knop 'Go to file'. Op deze pagina zie je bovenaan ´JiveDocumentation /´staan. Naast deze schuine streep typ je (een deel van) de bestandsnaam. In de lijst daaronder kan je dan klikken op het juiste document.
❕ Zorg ervoor dat je op de masterbranch zit wanneer je een zoekresultaat opent.
- (1): Dit is niet de masterbranch. Klik op het pijltje ernaast om naar de
- (2) masterbranch te gaan.
- Vind je iets niet terug? Contacteer dan Emilien en laat het hier weten.
Veel van de bestanden zijn in Markdown formaat. Je kan gewoon op deze bestanden klikken, en dan worden ze rechtstreeks getoond. Markdown is een manier om tekst weer te geven online. Door bestanden in Markdown op Github te plaatsen, worden ze automatisch rechtstreeks getoond.
Om je tekst te lay-outen, kan je hier hier terecht voor een algemeen overzicht, hier voor de basis syntax in meer detail, hier voor een gemakkelijk cheatsheet en hier voor emoji's because why not.
Een speciaal type markdown bestandhiervan zijn de README.md bestanden. Een .md bestand met zo'n naam, is het eerste bestand dat je ziet wanneer je een repository opent (zoals het overzichtsdocument (scroll naar onder)) of een map opent. Dit bestand zal je dus binnen elke map zien staan en wordt automatisch onder de inhoud getoond.
Andere formaten, zoals excel of word, moet je eerst downloaden. Klik hiervoor eerst op de file, en dan op 'Download'.
- Kleine wijzigingen mag je gewoon zo aanpassen.
- Wil je inhoudelijk iets veranderen ("deze afspraak vind ik inhoudelijk niet goed")? Zet het dan eerst op de agenda van de Redactiegroep.
- Voor inhoudelijke en grote wijzigingen maak je eerst (indien het nog niet bestaat) een Github issue aan waarnaar je vervolgens verwijst bij je aanpassingen.
- Als je een wijziging doet naar aanleiding van een discussie op Github, zet dan steeds de link naar die discussie in de beschrijving bij je "commit" bericht. Er wordt dan automatisch in die discussie een verwijzing naar je aanpassing toegevoegd. In het aangepaste document zal je automatisch kunnen zien op welke discussie je wijziging is gebaseerd. Als je schrijft 'closes url-van-het-issue', dan kan het Issue zelfs automatisch afgesloten worden.
Zie verder voor meer uitleg hoe je wijzigingen kan aanbrengen. Dit kan op Github zelf, of via Github Desktop.
- Vind je iets niet terug binnen de documentatie? Post het dan hier.
- Gestoten op een link die niet werkt? Vermeld ze hier.
- Een ander probleem? Maak dan hier een nieuw issue aan.
❕ Wil je een map aanmaken of toevoegen? Dan moet je Github Desktop gebruiken.
- Ga naar de map waarin je een bestand wil aanmaken. Klik op 'Add file' en kies dan voor 'Create new file' (1).
- Geef eerst een naam aan je file en eindig met ".md" anders wordt hij niet juist weergegeven (2).
- Schrijf in de witruimte je tekst (dit is in markdown formaat) (3). Je kan hierin gewoon typen, maar je moet zelf nog de lay-out toevoegen. Voor meer info, scroll terug naar 'Soorten bestanden en hoe deze te openen' > 'Markdown'.
- Je kan je file previewen door op het Oogje 'Preview' te klikken (4).
- Ben je tevreden met het resultaat? Scroll dan naar onder en beschrijf in de ruimte 'Create new file' kort wat je hebt gedaan, en daaronder nog wat meer uitleg indien je dit wenst (5).
- Klik dan op de groene 'Commit new file' knop die tevoorschijn komt (6). Vergeet niet te verwijzen naar eventuele Issues waarop je nieuwe pagina is gebaseerd (zie eerder).
- Na goedkeuring van mij of Joost zal de file dan toegevoegd worden.
❕ Door een Word-bestand als Markdown toe te voegen, wordt het bestand rechtstreeks getoond op Github en moet je het niet eerst downloaden.
- Maak je Word-bestand op
- Converteer het naar Markdown via een converter.
- Kopieer het naar je kladblok (Kladblok en Notepad++ zijn goeie opties)
- Sla dat bestand op als ´Naam dat je aan bestand wilt geven.md´.
- Ga naar de juiste map op Github, klik op ' Add file' en selecteer 'Upload files' (zie hierboven).
- Selecteer je bestand.
- Controleer zeker of alles van lay-out goed geconverteerd is. Moet je nog zaken aanpassen? Zie dan verder hoe je documenten moet bewerken.
- Beschrijf in de ruimte 'Create new file' kort wat je hebt gedaan, en daaronder nog wat meer uitleg indien je dit wenst.
- Klik dan op de groene 'Commit new file' knop die tevoorschijn komt. Vergeet niet te verwijzen naar eventuele Issues waarop je wijziging is gebaseerd (zie eerder).
- Na goedkeuring van mij of Joost zal de file dan toegevoegd worden.
- Kies dan voor 'Add file' en dan 'Upload files' (zie hierboven).
- Selecteer je bestand en laadt op.
- Beschrijf in de ruimte 'Create new file' kort wat je hebt gedaan, en daaronder nog wat meer uitleg indien je dit wenst.
- Klik dan op de groene 'Commit new file' knop die tevoorschijn komt. Vergeet niet te verwijzen naar eventuele Issues waarop je wijziging is gebaseerd (zie eerder)
- Na goedkeuring van mij of Joost zal de file dan toegevoegd worden.
- Open de markdown file of scroll naar onder in de map indien je de README file wil aanpassen.
- Klik op het potlood (1).
- Je kan binnen deze ruimte gewoon typen, maar je moet zelf nog de lay-out toevoegen (2). Voor meer info, scroll terug naar 'Soorten bestanden en hoe deze te openen' > 'Markdown'.
- Je kan je file previewen door op het Oogje 'Preview' te klikken (3).
- Ben je tevreden met het resultaat? Scroll dan naar onder en beschrijf in de ruimte 'Create new file' kort wat je hebt gedaan, en daaronder nog wat meer uitleg indien je dit wenst (5).
- Klik dan op de groene 'Commit new file' knop die tevoorschijn komt (6). Vergeet niet te verwijzen naar eventuele Issues waarop je wijziging is gebaseerd (zie eerder).
- Na goedkeuring van mij of Joost zal de file dan toegevoegd worden.
Dan moet je het bestand eerst downloaden, en daarna terug uploaden. Zie hierboven hoe je dat doet.
Via de Github Desktop applicatie kan je mappen, documenten toevoegen of bewerken op je computer zelf.
Kortweg komt het erop neer dat je via deze applicatie een kopie maakt op jouw pc van de gekozen Github repositories/repository. Binnen deze kopie vind je alle bestanden die zich bevinden binnen de repository. Door zaken aan te passen binnen jouw kloon kan je deze veranderingen dan binnentrekken binnen de 'echte' Github online.
Een groot voordeel van Github Desktop is dat je eerst in een kopie werkt en veranderingen niet automatisch doorstromen naar de 'echte' Github. Hierdoor is er meer ruimte om zaken uit te proberen.
💡 Meer informatie over hoe te beginnen met Github Desktop vind je hier. Daar wordt het voorbeeld voor de repository kadaster-post-processing getoond. De URL voor JiveDocumentation is dan:
´https://github.com/provinciesincijfers/JiveDocumentation´
Een tutorial vind je hier.
- Kloon de desbetreffende repository waarin je wil werken. Eens gekloond, hoef je dit niet meer te doen daarna. Zie hierboven hoe je dit doet.
- Zorg ervoor dat je current repository op 'JiveDocumentation' staat (1) en dat je in de masterbranch werkt (2).
- Heb je de repository al gekloond? Haal dan eerst de veranderingen die gemaakt zijn op Github zelf binnen. Dit gebeurt immers niet automatisch. Dit doe je door Github Desktop te openen, ervoor te zorgen dat je current repository op 'JiveDocumentation' staat (1) en je binnen de masterbranch werkt (2), en dan op 'Pull Origin' te klikken (3).
- Open de gekloonde repository (4). Deze ziet er net hetzelfde uit als je andere mappen op je pc.
- Voeg/Bewerk de bestanden die je wilt toevoegen/bewerken binnen je kloon. a. Markdown files maak je het best aan via je kladblok of Notepad++, dat je dan opslaat als bestandsnaam.md b. Voor het converteren van een Word- naar Markdown-bestand, zie hierboven onder 'Heb je een word bestand en wil je het als markdown bestand toevoegen?
- Keer terug naar de Github Desktop applicatie. Je zal zien dat er onder de tab Changes een opsomming zal staan van al je veranderingen (1). In de volgende screenshot paste ik het word-document 'Checklist grondige controle databank' aan.
- Typ in het vak onderaan naast je icoon een korte samenvatting van je veranderingen (2) en voorzie eventueel een meer uitgebreide beschrijving in het vak daaronder. Vergeet niet te verwijzen naar eventuele Issues waarop je wijziging is gebaseerd (zie eerder).
- Klik op 'Commit to master' (3).
- Rechts verschijnt de blauwe knop 'Push origin' (ziet er hetzelfde uit als de 'Pull origin' knop. Klik hierop om je veranderingen naar de 'echte' Github te laten doorstromen.
- Na goedkeuring van mij of Joost zullen de veranderingen dan toegevoegd worden.
- Hier vind je allerlei guides. De volgende kunnen zeer interessant zijn:
- Getting Started with GitHBub Pages: Voor wanneer je pagina's wilt bewerken.
- Master issues: Hoe je issues aanmaakt e.d.
- Mastering Markdown: meer informatie over Markdown.
- Een foto toevoegen kan het makkelijkst via Github Online. Dan kan je gewoon de foto copy pasten wanneer je een markdown document bewerkt binnen github. De juiste link verschijnt dan vanzelf. Via de Desktop applicatie kan dit niet.
- Mappen maak je aan of bewerk je het makkelijkst via Github Desktop.