In this blog post, we’d like to introduce you to the Sailfish OS Wiki. Over the last few months, various sailors have been busy writing documentation and adding it to the wiki, and while there is much more work to be done, it is now complete enough that we consider it to be “beta” stage. This blog post intends to describe why we consider the wiki to be so important, what sort of information can be found in it, our plan for community contributions to the wiki, and to point out some specific sections of the wiki which might be of most interest to our community.
About The Wiki
The Sailfish OS Wiki is intended to be a comprehensive, evolving, living document which describes in detail the various components which make up the Sailfish OS platform, and the interactions between each of those components. Having extensive documentation for Sailfish OS is extremely important for its growth as an open platform, as it greatly lowers the barrier to entry for contributions. Furthermore, as the platform evolves, it is important that the documentation evolves along with it – and it is precisely this aspect of the wiki format which makes it ideal for Sailfish OS documentation. The eventual goal we have for the Sailfish OS Wiki is that as community members contribute to the Sailfish OS platform through code contributions, they simultaneously contribute to the Sailfish OS platform by updating the documentation in the wiki related to the software component they have modified.
Having comprehensive platform documentation is critically important, however it is also vital that the information it contains be easily accessible. This means that the information must be separated into logical categories, cross-linked with related information, formatted appropriately for the intended audience, and edited both for consistency of form and style, and to ensure that copyrighted content is not added without permission. In that respect, we see the Sailfish OS Wiki as being similar to a software repository hosted on the Mer Project GitLab or on GitHub: the wiki will have maintainers and every change should be subject to review and approval by various contributors. We haven’t yet finalised what sort of process could be used for this type of contribution review, or how different access rights will be granted to contributing members of the project (including corporate contributors and community contributors), and this is something we are looking to discuss further with the community in the near future.
Architecture And Collaborative Development Documentation
Recently, sailors from Jolla have been adding documentation to a variety of sections in the wiki relating to both application development (that is, how to develop on top of the Sailfish OS platform) and system development (that is, how to develop the Sailfish OS platform itself). In this blog post, we’d like to point out two areas in particular: the architecture documentation, and the collaboration and contribution documentation. After reading those sections of the Sailfish OS Wiki, a prospective contributor should feel like they have the information they need to contribute to the Sailfish OS platform, be it a bug report, a unit test, a documentation improvement, or a bug fix or a new feature in a software component.
The architecture documentation in the Sailfish OS Wiki contains an overview of the Sailfish OS platform architecture. It describes the various levels of software components which build upon each other to provide the final user experience, from the low-level components like the Hardware Abstraction Layer, to various middleware components providing system services and access APIs, and high-level applications and services providing user-experience on top of the UI subsystem. After reading through those pages, you should have an understanding of how the various components of Sailfish OS fit together, and which components you might like to contribute to.
The collaborative development documentation in the Sailfish OS Wiki describes how to contribute to Sailfish OS. It includes information about filing bug reports, cloning source code repositories, editing code and creating change requests to the repository, how changes get reviewed and accepted and finally released, and how the quality assurance process works. It also includes a step-by-step example of how to contribute a patch to the Sailfish OS Browser, and finally includes a list of various components of the Sailfish OS platforms along with some developers who have experience developing those components, with whom you can get in contact if you wish to contribute there too!
The next steps for us include allowing community members to create accounts and add content and make changes themselves. As noted above, since we wish to have some process whereby contributions to the wiki can be reviewed similarly to how code is reviewed before being accepted into the repositories, we aren’t quite ready to open it up to everyone just yet. We need to devise some proposals for what this process might look like and what form it might take, and then discuss those proposals with the community, before implementing the best one. We will organise a Sailfish OS Community Meeting on IRC to discuss this topic in great detail, at some point in the near future.
Until then, if you have suggestions or want to report issues like poor formatting or broken links in the wiki, please contact David Greaves or Jarkko Lehtoranta via email or IRC.
We look forward to collaborating with everyone more closely in the future, and to building a more open future!
Sailfish OS Wiki Team