Iets over readme's, de eindgebruiker en de auteur

4.665 posts
Iets over readme's, de eindgebruiker en de auteur
« on: Sunday 11 January, 2015, 23:49:31 »
Als iemand van het download team hier op Treinpunt zie ik met grote regelmaat allerhande download voorbij komen. Daarnaast als gebruiker van dit forum zie ik evenveel problemen langs komen, waarvan veel in de beginne readme gerelateerd zijn. Deze post moet men zeker niet gaan opvatten als gedwongen aangelegenheid vanuit Treinpunt maar als advies uit mijn persoonlijke ervaring hiermee.

Voor elke eindgebruiker geldt natuurlijk dat hij/zij de readme moet lezen om eventuele speciale aandacht punten te ontdekken dan wel toe te passen, bijvoorbeeld het installeren van bepaalde assets of het uitvoeren van bepaalde handelingen. Om dit makkelijk te laten verlopen moet de readme echter wel van enige kwaliteit zijn en de juiste informatie beschikken. Helaas is er menig downloads waar wel wat haken en ogen aan zitten qua readme. Vaak is dit niet de schuld van de maker, de meeste zijn tenslotte nog onervaren met het aanbieden van content. Vandaar dit topic om elkaar te helpen en adviseren. Tevens misschien een mogelijkheid om je readme vast te tonen zodat mensen deze eventueel kunnen controleren of tips geven, je laat tenslotte ook de route/materiaal zelf (beta)testen voor perfectie, dus waarom de readme niet?


De Bestandsnaam

Laten we beginnen met de bestandsnaam van een readme en het bestandstype. Over het algemeen wordt de bestands naam readme toegepast. Dit is een heldere en duidelijke benaming van het bestand. Indien je kiest voor readme's in meerdere talen kan je ervoor kiezen meerdere vertaalde bestanden te gebruiken. De naamgeving vna deze bestanden kan op meerdere manieren. Een veel voorkomende manier om dit te doen is door "readme" letterlijk te vertalen. In het Nederlands wordt het dan bijvoorbeeld Leesmij en in het Duits liesmich. Dit is helder en duidelijk voor elke eindgebruiker.


Het bestandsformaat

Er kunnen verschillende bestandsformaten als readme gebruikt worden. Veel voorkomend is het simpele .txt bestand. Dit bestand kan vrijwel iedereen openen, maar heeft als nadeel dat er geen opmaak toegepast kan worden.
Als alternatief voor de .txt wordt vaak een .pdf gebruikt. Voordeel van de .pdf is dat de inhoudt niet gewijzigd kan worden en de opmaak vrij. Ook kan een PDF in tegenstelling tot een .txt afbeeldingen bevatten. Nadeel van de PDF is dat de eindgebruiker over een PDF reader moet beschikken, echter vrijwel elke eindgebruiker beschikt hier over.
2 minder gebruikte formaten zijn een html webpagina en een .rtf bestand.
De HTML webpagina heeft net als de .txt het voordeel dat vrijwel iedereen het kan openen, daarnaast is ook opmaak mogelijk. Nadelig aan de HTML is dat de auteur kennis over HTML moet hebben en eventuele afbeeldingen in de download als apart bestand moeten worden meegeleverd dan wel extern van internet geladen moeten worden.
RTF lijkt in enige vorm op de .txt, echter heeft het als voordeel dat er enige opmaak toegepast kan worden. Daarnaast kan het door vrijwel iedere Windows gebruiker geopend worden met het standaard Windows programma "wordpad". Ook vele andere tekstverwerkers kunnen die programma openen.

Onderstaand samenvattend de voor en tegens van verschillende bestanden:

.txt
VoordeelNadeel
Door iedereen te openenGeen opmaak mogelijk
Simpel te makenGeen afbeeldingen mogelijk
PDF
VoordeelNadeel
Vrij in opmaakAlleen te openen met PDF reader (bijv. adobe reader)
AfbeeldingenGroter bestand
Te vergrendelen tegen aanpassingen
HTML webpagina
VoordeelNadeel
Door vrijwel iedereen te openenMoeilijker te maken
Vrij in opmaak
Afbeeldingen (met kanttekening, zie tekst)
RTF (Rich Text Format)
VoordeelNadeel
Door vrijwel iedereen te openenNiet gebruikelijk
Beperkte opmaak mogelijkGeen afbeeldingen mogelijk

Overige bestanden kunnen beter gemeden worden als readme, hiervoor zijn verschillende redenen. Een vele gebruikt bestand wat beter niet gebruikt kan worden is een Word .doc of .docx. Hoewel deze bestanden een grote vrijheid kennen in het maken en gebruik van opmaak/plaatjes zijn ze voorde eindgebruiker niet altijd handig. Zo ziet het bestand er niet altijd in elke word versie het zelfde eruit en is er software nodig om het bestand te kunnen bekijken. De beste optie is het bestand in plaats van .doc of .docx op te slaan als PDF. Word 2007 en nieuwer heeft hier een ingebouwde optie voor. Indien een oudere versie gebruikt wordt kan je PDF bestanden maken met gratis online converters (Let op een eventuele watermerk!) of een PDF printer te installeren.
« Last Edit: Wednesday 02 March, 2016, 10:17:18 by jor[D]1 »

4.665 posts
Re: Iets over readme's, de eindgebruiker en de auteur
« Reply #1 on: Sunday 11 January, 2015, 23:49:41 »
In deze post kijken we naar de inhoud van een readme, dit is verreweg het belangrijkste onderdeel.
Een readme schrijven bestaat grofweg uit 5 stappen;
  • Introductie
  • Algemene informatie
  • Instructie
  • Afsluiting
  • Controle


De introductie

Over het algemeen wordt de readme begonnen met een informatie blokje beginnend met een titel, zo is het gelijk duidelijk bij welke download/route/asset de readme hoort.
In sommige gevallen is het slim om iets langer na te denken over de titel. Bijvoorbeeld als er een route Leiden - Utrecht wordt gemaakt zou je zeggen ik kies de titel: Leiden - Utrecht. Echter als je verder gaat met bouwen wordt misschien het traject Alphen - Gouda en later Utrecht - Gouda- Rotterdam ook toegevoegd. De originele titel dekt nu niet echt meer de route en voor volgende versies zal je dus een andere titel moeten gebruiken. Dit kan tot verwarring leiden als iemand de route bijvoorbeeld 10 jaar later zoekt en niks kan vinden omdat er op Leiden - Utrecht wordt gezoek en de route allang niet meer zo heet. Nu klinkt dat misschien raar, maar kijk naar de oude MSTS. Onthoud dat je werk lang online blijft staan en je readme later nóg belangrijker is dan nu, omdat je later misschien niet meer actief bent met railworks of andere software. Een goede titel voor een route Leiden - Utrecht kan bijvoorbeeld zijn: "Groene hart route". Natuurlijk ontkom je er soms later toch niet aan de naam te wijzigen, maar die kans is zo al een stuk kleiner.

Een volgend onderdeel wat handig is om in de readme te zetten is een versie nummer en een publicatie datum. Voor de auteur misschien minder van belang maar voor de eind gebruiker over een aantal jaar misschien wel. Na verloop van een aantal jaar en versies kunnen er op verschillende sites verschillende versies circuleren. Op dat moment is het voor zowel de eindgebruiker als de maker meestal makkelijk om te zien welke versie ergens te vinden is.

Na de versie/datum is het verstandig aan te geven voor welke software dan wel software versie de route ontwikkeld is. Dit hoeft niet te betekenen dat het niet werkt op andere versies, echter hiervan weet jij als auteur het zeker en heb je het waarschijnlijk ook getest dan wel laten testen.

De volgende stap in die blokje contact gegevens kunnen zijn. Dit is een redelijk belangrijk onderdeel van de readme wat vaak, (te vaak), vergeten wordt. Naast dat het eventueel handig kan zijn dat eventuele gebruikers je kunnen bereiken. Ben je natuurlijk als auteur ook trots op je werk, dus waarom zal je je naam er niet aan verbinden. Een schilder of schrijver doet het ook. Je echte naam vermelden hoeft natuurlijk niet, en je zou bijvoorbeeld ook een alias kunnen gebruiken. Naast of onder je naam kan je een email adres of andere contact mogelijkheid vermelden.


Het algemene deel

Na een introductie blokje heb je de mogelijkheid een aantal zaken toe te voegen afhankelijk of je ze nodig acht. Dit zijn zaken als wat algemene (historische) informatie, benodigde andere software/downloads, bedankjes aan helpende handen, bronnen, changelog en ga zo maar door.
Belangrijk is dat je deze onderdelen van elkaar scheidt door middel van alinea's en kopjes. Dit maakt het makkelijker de readme te lezen en begrijpen. Een aantal van deze onderdelen spreken ook voor zich, echter over de benodigde software is nog het een en ander te vertellen.
Dit is eigenlijk bij downloads welke dit hebben het belangrijkste onderdeel van de readme. Wat echter vaak gebeurt is dat er een aantal "kreten" worden geplaatst die nu actueel zijn echter niet toekomst vast zijn.
Een voorbeeld van zo'n kreet is bijvoorbeeld: "Alles van COHA" of "Alle freeware van Christrains"
Probleem met dit soort uitleg is dat deze niet actueel blijft, ontwikkelaars blijven vrijwel continue nieuwe producten/downloads uitbrengen. Hierdoor zal de eind gebruiker uiteindelijk teveel gaan downloaden, en indien de content niet meer makkelijk te krijgen is niet weten wat hij moet gaan zoeken.
Een goede readme beschikt daarom over een duidelijk lijst van benodigde content software, maar wat is een goede lijst. Een goede lijst geeft tenminste de volgende informatie over de benodigde software:
  • Titel/Naam
  • Versie en of Datum
  • Auteur/Uitgever
  • Link

De link is natuurlijk een geval apart, hoe geef je die weer? Dit kan op meerdere manier. Je kan direct naar de download/product verwijzen. Dit heeft als voordeel dat de eind gebruik gelijk op de juiste pagina is. Echter indien de site bijvoorbeeld wordt verbouwt is de kans groot dat de links veranderen. Als alternatief zou een link naar de homepage van de website gebruikt kunnen worden. Immers de gegevens van de benodigde download zijn zeer duidelijk weergegeven en de eindgebruiker moet met redelijk gemak de benodigde spullen nu kunnen vinden. Het ligt een beetje aan de persoonlijke voorkeur wat men gebruikt. Belangrijk is links ter vermijden die naar gratis hosting sites als mediafire, dropbox etc. leiden. Deze links zijn met regelmaat na een aantal maanden/jaar onbereikbaar. Indien er een alternatief is gebruik deze dan.


De instructie

Het volgende onderdeel van de readme is meestal de installatie instructie. Dit lijkt het belangrijkste deel, maar dat is maar de vraag. Duidelijke titel, versie/datum en benodigde software zijn misschien wel net zo belangrijk.
Een goede installatie instructie gaat ervan uit dat de eindgebruiker niks weet. Om het voor de eindgebruiker makkelijk te maken kun je het besten in stappen werken.

De stappen zijn afhankelijk van je download en hoe deze wordt geïnstalleerd, dus concrete voorbeelden zijn moeilijk te geven. Echter het is wel belangrijk een duidelijke volgorde aan te geven. Doe dit met behulp van bijvoorbeeld nummertjes. Dit is zeer makkelijk en duidelijk.


De afsluiting

De readme wordt vaak afgesloten met een disclaimer of copyright informatie. Hierin stelt de auteur bepaalde voorwaarden regels omtrent de download/software/assets. In dit onderdeel kom je dit soort informatie tegen:
Quote from: Tom Jansen, MSTS "NS Bollenwagen Ubcs v1" readme
1 Dit model mag niet op CD's e.d. meegeleverd worden zonder toestemming van de auteur.
2 De inhoud van deze download is freeware en mag op geen enkele manier commercieel gebruikt worden.
3 Websites dienen eerst toestemming te vragen voor distributie van deze download.
4 Repainters dienen eerst toestemming te vragen voor distributie van in deze download aanwezige content, ook als deze content aangepast is.      
5 Het installeren van deze content is op eigen risico. De auteur is niet aansprakelijk voor schade aan uw computer.
6 De rechten van de ontwerpers dienen gerespecteerd te worden.
7 Wijzigingen in deze Lees Mij aanbrengen is verboden.

Verder wordt meestal afgesloten met een copyright melding, dan wel licentie overeenkomst. Dit klinkt redelijk ingewikkeld maar hoeft dat niet te zijn. In theorie hoeft het ook niet vermeldt te worden, echter is het wel zo duidelijk als het wel vermeld wordt.
Een copyright vermelding kan zo simpel zijn als:
Copyright © 2015 Pietje Puk

Of indien er een speciale licentie aan het werk hangt een vermelding van bijvoorbeeld Creative commons, of GPL. Deze licenties laten bijvoorbeeld verspreiding onder bepaalde voorwaarde toe. Exacte details over hun uitwerking kan je op de betreffende websites vinden: http://creativecommons.nl/ en  http://www.gnu.org/licenses/gpl.html


De controle

Als je je readme voltooid hebt controleer hem dan grondig. Check taal en spel fouten, interpunctie, hoofdletters, opmaak etc. Laat eventueel iemand anders er nog naar kijken. Een foutloze readme is beslist makkelijker te begrijpen. Controleer tevens eventuele links en de datum/versie nummer als je een oude readme update.
Als laatste vergeet hem natuurlijk niet aan je download toe te voegen. :P



Ter afsluiting van dit verhaal over readme's heb ik een voorbeeld readme gemaakt in alle 4 de aangeraden bestands formaten. Deze zijn te downloaden in de bijlage.
-Komen er aan-
Als er mensen op en aanmerkingen of andere goede tips hebben mogen die natuurlijk gegeven worden en kunnen ze aan de tekst worden toegevoegt. Tevens wil ik graag aan makers van content de mogelijkheid vrij laten om hun readme in een reactie achter te laten om feedback van andere leden/geïnteresserde te krijgen.
Als laatste wil ik er nogmaals op wijzen dat dit geen regels zijn, noch van mij, noch van treinpunt, dit is een advies wat vrij wel of niet te volgen is. Ik hoor ook graag op of aanmerkingen op bovenstaand advies.


Dit werk is gelicenseerd onder de licentie Creative Commons Naamsvermelding-NietCommercieel-GelijkDelen 4.0 Internationaal.  Ga naar http://creativecommons.org/licenses/by-nc-sa/4.0/ om een kopie van de licentie te kunnen lezen.
« Last Edit: Monday 12 January, 2015, 00:06:41 by jor[D]1 »

23 posts
Re: Iets over readme's, de eindgebruiker en de auteur
« Reply #2 on: Monday 12 January, 2015, 00:49:28 »
Heel goed Jordi. Je hebt er echt werk van gemaakt.

Ik ben ook voor een duidelijke readme bestand. Ik heb al meerdere malen als newbee dingen tegen gekomen die eigenlijk verholpen konden worden als deze in de readme stond vermeld.

Offline Tom
Voorheen: nstomjanssen2000
Geboren Nijmegenaar
2.373 posts
Re: Iets over readme's, de eindgebruiker en de auteur
« Reply #3 on: Monday 12 January, 2015, 19:03:36 »
Disclaimer over de disclaimer: Deze is hetzelfde als die in Jeroens K1's. (uiteraard wel overlegd met hem)

198 posts
Re: Iets over readme's, de eindgebruiker en de auteur
« Reply #4 on: Tuesday 13 January, 2015, 20:26:36 »
Goed gedaan! Dank je wel. Een kleine aanvullende tip. Geef op de downloadpagina een indicatie van extra content die je nodig hebt. Het is vervelend als je een groot bestand hebt gedownload en geopend om dan tot de ontdekking te komen dat je nog tien andere downloads moet opsporen of een enorme hoeveelheid payware nodig hebt voor één scenario. Natuurlijk is er ook RW Tools, maar dat werkt niet echt lekker als je veel assets moet vervangen.

**
TreinPunt.NL Vriend
1.158 posts
Re: Iets over readme's, de eindgebruiker en de auteur
« Reply #5 on: Tuesday 01 March, 2016, 21:21:59 »
Mooi gedaan jor[D]1,

nog een voordeel van pdf, deze is te beveiligen.  Zo kan hij niet aangepast worden !
als je alleen tekst gebruikt is een pdf niet veel groter dan een txt bestand.
maar zeker wel een mooiere en duidelijke opmaak.
ik probeer ook echt met elke versie de readme beter en duidelijker te maken.
al kan dat soms wel lastig zijn als het al een behoorlijke tijd geleden is :D

toon je waardeering met een donatie ! ( vrijblijvend ! ) : http://nl.dreamordonate.com/dromen/ts2016-zw-nl

4.665 posts
Re: Iets over readme's, de eindgebruiker en de auteur
« Reply #6 on: Wednesday 02 March, 2016, 10:18:30 »
Bedankt leon, dat is inderdaad nog een voordeel van een pdf. Hoewel het voor een readme niet van zeer groot belang is heb het nog toegevoeg aan het overzicht.

Mvg Jordi