Ontwikkelen van onze Developer Docs
Vanuit een technisch perspectief heeft Jolla lange tijd een strategie met drie pijlers gehanteerd; die pijlers zijn Sailfish OS, Android App Support en ons Developer-aanbod. Sami's recente presentatie tijdens de tienjarige viering in Berlijn, zul je de laatste van deze hebben gezien als een van onze unieke troeven: een "Ontwikkelaarservaring van wereldklasse".
Dus hoewel onze ontwikkeltools misschien alleen direct worden gebruikt door een klein deel van ons totale gebruikersbestand, weten we dat het bieden van uitstekende ontwikkeltools absoluut essentieel is om een bloeiend ecosysteem van derden te garanderen en om onze partners in staat te stellen succesvol te bouwen op Sailfish OS en onze Android App Support.
Daarom hebben we de afgelopen jaren hard gewerkt om een groot aantal veranderingen door te voeren.
In juli 2019 hebben we geïntroduceerd op het nieuwe sfdk opdrachtregelinterface voor het bouwen van toepassingen. Dit begon ons op weg naar het samenvoegen van de Platform en Applicatie SDK's. Onze bedoeling op lange termijn was om het niet alleen gemakkelijker te maken voor ontwikkelaars – die slechts één tool zouden moeten gebruiken in plaats van twee – maar ook voor onszelf op het gebied van onderhoud. Hoe minder werk we hoeven te doen voor dezelfde resultaten, hoe beter. Dit werk is in een hoog tempo voortgezet, zodat sfdk is nu een levensvatbaar alternatief geworden voor de Platform SDK voor alle, op een paar randgevallen na, en voor zover we nu intern zijn begonnen met de overgang naar het gebruik van sfdk voor het zelf ontwikkelen van Sailfish OS.
In april 2020 werd de nieuwe Docker-gebaseerde build-engine geïntroduceerd als alternatief voor onze eerbiedwaardige VirtualBox-gebaseerde aanpak. Docker biedt dezelfde zelfstandige, platformonafhankelijke en OS-onafhankelijke omgeving als VirtualBox, zodat de SDK consistent werkt voor alle ontwikkelaars, ongeacht het installatieplatform of de omgeving die ze gebruiken. Maar het is ook slanker, efficiënter en flexibeler, wat uiteindelijk resulteert in snellere builds.
Toen introduceerden we in juli 2020 onze nieuwe Discoursgebaseerd forum. Discourse biedt een schonere, modernere interface dan het eerdere forum op basis van AskBot, en we zijn erg blij met het resultaat. De indruk die we krijgen is dat ontwikkelaars het meeste uit het zeer actieve forum halen en dat zowel gebruikers als ontwikkelaars de nieuwe functies waarderen.
We’ve also been working hard to improve our API support. Like any Linux distribution, Sailfish OS offers a huge number of useful developer-oriented libraries and APIs. Many of these are in a state of continuous development, and while they’re changing it wouldn’t be appropriate for us to commit to supporting them over the longer term. Those that we consider to be both well-designed and stable we elevate to “Harbour-supported” APIs. In order to avoid future breakages, apps in the Jolla Store are only allowed to access these supported APIs, so it’s important we balance both breadth and stability. Over the last year we’ve added many new APIs to this officially supported list, including the Sharing API, the Sandboxing API, the WebView API and the Camera API. And we’ve also announced that the Web Authorization API and the MPRIS API are on track for official support in the near future.
Grote veranderingen, maar we hebben geen plannen om het daar te laten. Een van de gebieden die we al een tijdje willen verbeteren, is onze documentatie voor ontwikkelaars. Tot nu toe is dit enigszins verspreid, met wat nuttig materiaal op het forum, maar met de meeste officiële documentatie die op onze statische API-documentatie site, of op de Ontwikkelaarswiki. De eerste biedt documentatie die rechtstreeks uit de broncode voor specifieke API's is gegenereerd, en als zodanig kan elke ontwikkelaar een pull-verzoek indienen om de tekst te bewerken. Deze documentatie is echter beperkt tot alleen de door Harbour ondersteunde API's. De laatste bredere documentatie kan daarentegen alleen worden bewerkt door Jolla-medewerkers, en veel ontwikkelaars hebben om flexibelere toegang gevraagd om hen in staat te stellen hun eigen verbeteringen en bewerkingen aan de tekst aan te brengen.
Daarom zijn we erg blij om de release van onze nieuwe Sailfish OS Documentatie site. Het vervangt de Developer Wiki en combineert de breedte van zijn onderwerpen met de pull-request-gebaseerde bewerkingsbenadering van onze API-documentatie, maar gestroomlijnd om het proces nog eenvoudiger voor u te maken.
We hebben ongelooflijk goed nagedacht over de beste manier om kwaliteitsdocumentatie te garanderen, terwijl we ook een effectief proces mogelijk maakten voor zowel onze partners als leden van de community om de documentatie rechtstreeks te verbeteren. Onze conclusie was dat we dezelfde aanpak moeten gebruiken die ontwikkelaars al gebruiken om bij te dragen aan de Sailfish OS-broncode, maar deze uit te breiden naar al onze documentatie.
Daartoe worden de nieuwe Sailfish OS-documentatiepagina's gemaakt met behulp van de veelgebruikte en eenvoudig te leren Markdown-syntaxis en opgeslagen in onze documentatie GitHub repository. Anyone is able to fork this, make changes, and then submit a pull-request for us to integrate their changes into our own copy. On our side, we will then review any pull-requests and work with contributors to refine them as needed. Once a pull-request is accepted we’ll merge it into our repository, triggering the documentation site to be automatically populated with the new information and edits. The process integrates a simple Contributor Licence Agreement step, and all of the resulting docs will be CC BY-NC-SA -gelicentieerd.
Praktisch gezien, als je wijzigingen wilt voorstellen, klik je gewoon op de link "Deze pagina op GitHub bewerken" onderaan elke pagina. Dit is een zeer standaardproces dat bekend zal zijn bij iedereen die aan open source-projecten heeft gewerkt. Het is heel eenvoudig, het staat bewerkingen toe van iedereen die geïnteresseerd is en bereid is om bij te dragen, maar het zorgt er ook voor dat we bij Jolla de hoogste kwaliteit documentatie kunnen behouden die Sailfish OS-ontwikkelaars van ons gewend zijn.
Voor degenen die geïnteresseerd zijn in hoe de backend werkt, gebruiken we Alleen de documenten om de bronmarkering om te zetten in de uiteindelijke HTML-uitvoer. Dit geeft ons ook de mogelijkheid om nieuwe bijdragen van de gemeenschap op het gebied van webdesign uit te nodigen. We weten dat velen van jullie geweldige vaardigheden hebben op dit gebied, en als je suggesties hebt voor het verbeteren van de look-and-feel van de documentatie, zijn we open voor je pull-aanvragen ook hierover.
Met de site vanaf vandaag hebben we wat tijd besteed aan het opruimen van dingen, maar je zult merken dat de nieuwe site qua structuur en inhoud grotendeels vergelijkbaar is met de vorige documentatiesite. Met de nieuwe mogelijkheid om eenvoudig wijzigingen van derden op te nemen, hopen we echter dat deze veel sneller zal evolueren en verbeteren dan voorheen het geval was. Als je een fout opmerkt of als er iets verandert, dien dan een pull-verzoek bij ons in zodat iedereen hiervan kan profiteren.
We zijn ook op zoek naar het samenvoegen van de statische API-documenten in de nieuwe site, maar dit vereist enkele technische verdraaiingen, en daar zijn we nog niet helemaal lenig genoeg voor. Het is altijd goed om in de toekomst iets te hebben om naar te streven.
We hopen echt dat je geniet van de nieuwe Sailfish OS Documentatie Site, zowel wat betreft het vinden van de informatie die je nodig hebt, als het proces om deze bij te werken met nieuwe informatie. We hopen dat het hetzelfde succes zal brengen in de documentatie die het forum ter discussie heeft gesteld.
THE POST Ontwikkelen van onze Developer Docs verscheen voor het eerst op Jolla Blog.
Laatste reacties