Gnome Foundation huurt schrijver in voor documentatie

Een vaak gehoorde klacht over open-source software is ontbrekende, verouderde of onduidelijke documentatie. Dit is ook het geval bij de documentatie voor programmeurs van het Gnome-project. De Gnome Foundation, de stichting die de ontwikkelingen van de Unix-desktopomgeving Gnome aanstuurt, heeft daarom besloten een schrijver in te huren die openbare documentatie gaat schrijven waarin wordt uitgelegd hoe men software kan ontwikkelen voor Gnome.

Tijdens de Gnome Summit 2005, dat eerder deze maand plaatsvond, werd dit bekendgemaakt. De schrijver die de taak op zich heeft genomen om de documentatie te schrijven is Shaun McCance. De stukken die hij zal schrijven zullen met name gericht zijn op ontwikkelaars die nog geen ervaring hebben met het schrijven van software voor Gnome en omvat het hele spectrum van Gnome-technologieën zoals Gstreamer, gconf, gnome-vfs, gnome-print en de diverse taalbindingen. Het is niet bekend wanneer de documentatie gereed moet zijn.

Reacties (13)

Aan de ene kant een goeie ontwikkeling omdat de kwaliteit *waarschijnlijk* goed zal zijn; aan de andere kant is dit niet helemaal des Gromes, want dan kan je net zo goed programmeurs gaan betalen om software te schrijven.

Ik vind dat het schrijven van goeie software ook inhoudt dat je degelijke (=kloppende, duidelijke, complete en up-to-date) documentatie schrijft.

Misschien niet een van de leukste klusjes, maar zelf merk ik bij het schrijven van documentatie altijd hiaten in mijn software en inconsistenties, dus is het (vind ik!) wel degelijk onderdeel van het programmeren. Het dwingt je om na te denken over hetgeen je gemaakt hebt, en dat is altijd goed.

Dus: op zich goed voor de korte termijn maar een goeie programmeur zou dit zelf moeten kunnen doen.

Let wel: het schrijven van documentatie is wat anders dan de redactie of vertaling ervan natuurlijk. Een programmeur mag best taalfouten e.d. maken in haar/zijn documentatie.

Dat het alleen goed is voor de korte termijn ben ik het niet mee eens.
Het schrijven van documentatie kan een hulpmiddel zijn om de software te kunnen aanpassen. Maar het schrijven heeft dat niet tot doel. Net als dat je software maakt voor gebruikers maak je die documentatie voor gebruikers. Als je schrijven van documentatie door programmeurs laat doen om de software te verbeteren ben verkeerd aan het ontwikkelen. Natuurlijk betekent dat niet dat ontwikkelaars er dan niet bij betrokken moeten zijn. Je kan net zo min van een goed schrijver verwachten dat hij goed inzicht heeft in hoe de software in elkaar zit als dat je van een programmeur kan verwachten dat die ook zeer goed in het schrijven van documentatie voor gebruikers is. Ieder zijn vakgebied.

Het schrijven van documentatie kan een hulpmiddel zijn om de software te kunnen aanpassen. Maar het schrijven heeft dat niet tot doel.

Voor mij persoonlijk wel. Ik schrijf software, debug het en schrijf de documentatie. Tijdens het schrijven van de documentatie vallen me vaak dingen op die niet compleet zijn of niet eenduidig. Voor mij geldt dus dat het schrijven van documentatie een hulpmiddel is om de software te verbeteren.

In eerste instantie had ik niet gezien dat het om documentatie ging die nieuwe programmeurs moet helpen te programmeren. In dat geval zeg ik: korte maar krachtige documentatie en lees vooral heel veel code die goed becommentarieerd is.

ACM Queue schreef: Comment is more important then code, en daar ben ik het helemaal mee eens. Uit het commentaar van een code moet je de code kunnen afleiden, niet andersom. Hier het hele artikel: http://acmqueue.com/modul...ntent&pa=showpage&pid=290

Grappige stelling.

Terwijl juist veel programmeurs aanhanger zijn van het idee dat als code documentatie nodig heeft om begrepen te worden, de code niet goed is.

Het enige wat je zou hoeven documenteren is de interface. Als je de code zélf moet documenteren dan programmeer je waarschijnlijk omslachtiger dan nodig is.

Het gaat hier om het schrijven van documentatie voor mensen die willen beginnen met programmeren voor GNOME.

De Gnome Foundation [...] heeft daarom besloten een schrijver in te huren die openbare documentatie gaat schrijven waarin wordt uitgelegd hoe men software kan ontwikkelen voor Gnome.

Er zijn twee soorten documentatie:
1) Eindgebruikers documentatie
2) Onderhoudsdocumentatie/technische documentatie

1) is erg belangrijk zodat eindgebruikers weten hoe ze het moeten gebruiken, en dat is dus waarvoor de schrijver is ingehuurd
2) is net zo belangrijk, aangezien dat voor toekomstig onderhoud, wijzigingen aan het product en dergelijke erg handig is, zeker als de oorspronkelijke ontwikkelaars al lang elders aan de slag zijn

Verder is het zeker zo dat het in eerste instantie laten schrijven van documentatie door de ontwikkelaar zelf erg handig kan zijn doordat er nog eens over nagedacht wordt en dat de ontwikkelaar er misschien zelf achter komt dat een verzonnen oplossing toch niet zo handig is.

Ik zie iig vaak genoeg dat veel ontwikkelaars net iets te weinig de echte eindgebruiker in het achterhoofd hebben en daardoor in eerste instanties onhandig oplossingen bedenken, wat dan weer op verzoeken van klanten, meldingen van een helpdesk of verkoopteam/account management aangepakt moet worden.

1) Eindgebruikers documentatie
...
1) is erg belangrijk zodat eindgebruikers weten hoe ze het moeten gebruiken, en dat is dus waarvoor de schrijver is ingehuurd

Lees het artikel nou even, het is al zo kort!

Dit is ook het geval bij de documentatie voor programmeurs van het Gnome-project. De Gnome Foundation, de stichting die de ontwikkelingen van de Unix-desktopomgeving Gnome aanstuurt, heeft daarom besloten een schrijver in te huren die openbare documentatie gaat schrijven waarin wordt uitgelegd hoe men software kan ontwikkelen voor Gnome.

Of heb je 1 en 2 omgedraaid

Ik wilde voor KDE wel gaan vertalen (dus nog niets eens zelf aan de documentatie beginnen). Maar de kwaliteits-eisen zijn daar zo hoog dat ik mijn idee maar wegstopte. Ik denk dat Nederlands-(hoog)leraren er wel mee uit de voeten kunnen.

Ik draai SuSE en ik moet zeggen dat ik de documentatie juist heel compleet vind. Moet je natuurlijk wel alle manuals installeren (via Yast een eitje).

Een schrijver inhuren is misschien handig maar die schrijver moet dan dus elk programma doorspitten en ook even gebruiken (anders schrijf je snel een niet lekker lopende documentatie)

Nouja, ik vind het initiatief in ieder geval erg fijn.

@ BoGu5: Sorry, je hebt gelijk. Maar mijn post blijft, hoewel off-topic, toch misschien wel intressant.

Het gaat niet om eindgebruikserdocumentatie maar om documentatie voor programmeurs

heeft daarom besloten een schrijver

Eén schrijver!?!?!??! Wow, die heeft voor de eerste 30 jaar wel werk klaar liggen.

dat hangt er natuurlijk vanaf hoe diepgaand zijn werk is, en hoeveel hij kan copy/pasten uit oudere documentatie

Zeer zeker een goede zaak, goede documentatie bij ontwikkelen van software is een must. Het levert goede geoptimaliseerde software op

Hmm, "normaal" gesproken heb je een systeem-designer die de grootste lijnen uitzet voor een kompleet (software)systeem, en een aantal software designers die de specifiacties uitwerken tot high-level software designs voor de verschillende onderdelen.
De programmeurs gebruiken deze designs dan om detail- & implementatiedesigns te maken, pas daarna ga je programmeren.

Hier wordt zo te zien toch een beetje software archeologie bedreven (kan nog steeds zeer nuttig zijn), dus ik wens deze schrijver een hoop sterkte om tot een coherent verhaal te komen...