Docs Contribution
First of all - thank you! Contributions to the wiki are very welcome :)
The Sailfish OS Documentation should be a reliable and accurate source of information and it’s important that we work together to ensure this. What this means in practice is that we all need to follow some guidelines for docs contributions.
- Search: There’s a lot of content in the docs and in the API Documentation - make sure the information you want to contribute isn’t mentioned elsewhere. If it is then strongly consider including a suitable link instead (and by ‘strongly consider’ we’re just being polite - don’t duplicate information!)
- Where: The Sailfish OS Documentation is divided into two areas: support/integration content and reference content. The docs should be used for guidance documentation (this is typically conversational and gives a high level explanation). Detailed reference information and anything more than minimal code snippets usually belongs in or near the source code - see the API Documentation Contributions page for more about that.
- Location: Think carefully about where your content belongs - if in doubt, raise an issue in the docs Git repo. Especially if you are planning to change the nav structure.
- Consistency: Below are some links to templates or check pages. These are intended to both provide some consistency to similar pages and to remind you what kind of content should be included.
- Public: Contributions are public and will be published using the licence shown at the bottom of each docs page. Once information is published it cannot be reliably deleted from the internet so please bear that in mind. Changes are also stored (and linked to your account) in the git commit logs - make sure you’re happy with all this.
- Style: The Sailfish OS Documentation style is conversational and friendly - don’t try to make things sound too formal and technical, the OS is complicated enough as it is! On the other hand be accurate and use the correct technical terms where it makes sense - you’re talking to the other competent engineers, not pointy-haired managers ;)
- Legal: be aware of licences and copyright. You should only add content you create or can attribute under a suitable licence.
Having said all that:
- Add: Get typing - think about who’s reading your work and ensure it’s appropriate and relevant.
- Improve: If you know something is missing, mistyped, or misleading then please fix it. If you aren’t confident then feel free to reach out to us and make sure you’ve got your facts right - this is really important work and as a bonus if you say to someone “I checked the docs and still don’t quite understand - explain it to me and I’ll improve the documentation,” then you’re likely to get a lot more help.
There are a few areas of the site that should be pretty consistent so we’ve started a list of checklists for contributing documentation on: