Developing our Developer Docs
From a technical perspective Jolla has for a long time operated a three-pillar strategy; those pillars being Sailfish OS, Android App Support and our Developer Offering. If you watched Sami’s recent presentation at the ten year celebrations in Berlin, you’ll have seen the last of these highlighted as one of our unique assets: a “World-Class Developer Experience”.
So even though our developer tools may only be directly used by a small fraction of our overall user base, we know that providing excellent developer tools is absolutely essential for ensuring a flourishing third-party ecosystem, and for allowing our partners to build successfully on top of Sailfish OS and our Android App Support.
To this end, we’ve worked hard to introduce a host of changes over the last few years.
Back in July 2019 we introduced the new sfdk command line interface for building applications. This started us on a path towards merging the Platform and Application SDKs. Our long-term intention with this has been to make it easier not just for developers – who would need to use only one tool rather than two – but also for ourselves in terms of maintenance. The less work we have to do for the same results the better. This work has continued apace so that sfdk has now become a viable alternative to the Platform SDK for all but a few edge cases, and to the extent that we have now started the transition internally to using sfdk for developing Sailfish OS itself.
In April 2020 the new Docker-based build engine was introduced as an alternative to our venerable VirtualBox-based approach. Docker provides the same self-contained, cross-platform and OS-independent environment as VirtualBox, ensuring the SDK works consistently for all developers independent of the installation platform or environment they use. But it’s also leaner, more efficient and more flexible, ultimately resulting in faster builds.
Then in July 2020 we introduced our new Discourse-based forum. Discourse provides a cleaner, more modern interface than the earlier AskBot-based forum, and we’re very pleased with the result. The impression we get is that developers are making the most of the very active forum, and that both users and developers alike appreciate the new features.
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.
Big changes, but we have no plans to leave it there. One of the areas that we’ve been planning to improve for a while has been our Developer Documentation. Up to now this has been somewhat scattered, with some useful material on the forum, but with most official documentation living either on our static API documentation site, or on the Developer Wiki. The former offers documentation generated directly from the source code for specific APIs, and as such any developer can submit a pull-request to edit the text. However, this documentation is restricted to just the Harbour-supported APIs. In contrast the latter broader documentation can only be edited by Jolla employees, and many developers have been requesting more flexible access to allow them to make their own improvements and edits to the text.
That’s why we’re really happy to announce the release of our new Sailfish OS Documentation site. It obsoletes the Developer Wiki, and combines the breadth of its topics with the pull-request-based editing approach of our API documentation, but streamlined to make the process even easier for you.
We thought incredibly hard about the best way to ensure quality documentation, while also allowing an effective process for both our partners and community members to make direct improvements to the documentation. Our conclusion was that we should use the same approach that developers are already using to contribute to the Sailfish OS source code, but extending it to all of our documentation.
To this end, the new Sailfish OS Documentation pages are created using the widely used and simple to learn Markdown syntax and stored in our documentation 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 -licensed.
Practically speaking, if you want to propose changes, just hit the “Edit this page on GitHub” link at the bottom of any page. This is a very standard process which will be familiar to anyone who’s worked on open source projects. It’s very simple, allowing edits from anyone interested and willing to contribute, but also ensuring we at Jolla can maintain the utmost quality of documentation that Sailfish OS developers have come to expect from us.
For those interested in how the backend works, we’re using Just the Docs to convert the source Markdown into the final HTML output. This also gives us the opportunity to invite new contributions from the community in the area of Web design. We know many of you have great skills in this area, and if you have suggestions for how to improve the look-and-feel of the documentation, we’re open to your pull requests on this too.
With the site as-of today, we’ve spent some time cleaning things up, but you’ll find the new site to be largely similar in terms of both structure and content to the previous documentation site. However, with the new ability to easily incorporate third-party changes, we’re hoping it will evolve and improve far more rapidly than was the case previously. If you notice a mistake, or if something changes, submit a pull-request to us so that everyone can benefit.
We’re also looking at merging the static API docs into the new site, but this requires some technical contortions, and we’re not quite limber enough for that yet. It’s always good to have something to aim for in the future.
We really hope you enjoy the new Sailfish OS Documentation Site, both in terms of finding the information you need, and the process for updating it with new information. Our hope is that it will bring the same success to documentation that the forum has brought to discussion.
The post Developing our Developer Docs appeared first on Jolla Blog.
Laatste reacties