What should SailfishOS documentation be providing?

asked 2016-02-09 17:46:57 +0300

lbt

6514 ●41 ●48 ●51

moderator

http://www.merproject.org...

updated 2016-02-10 11:50:28 +0300

We're doing a review of the documentation around SailfishOS and want to start getting some input.

This is likely to be a sailfishos.org site and is intended for everyone (community, companies) interested in sfos development in any role (apps, UI, middleware, hardware, sysadmin, management...)

At the moment we're pulling together an outline and would be interested in what you'd like to see.

Here's a summary

Navigation
Introduction
- Welcome to SailfishOS
- Understanding Open Source
User guide / Tutorial
Guides by role / process / task (HOWTO)
- Development Roles
  - Introduction
  - Application developer
  - UI developer
  - Platform developer
  - HA developer
  - Build / Release engineer
  - QA engineer
- Collaborative development process
- Tasks
Platform Information (Coding Reference)
- Architecture
  - Overview
  - Packaging
  - Security
  - Internationalisation/Localisation
  - Qt
  - Core Areas / APIs (including SFOS Apps)
- UI
  - Principles
  - Interactions
  - Silica Component API
- Hardware
  - Hardware Adaptation Development Kit
  - Flashing
  - Devices
- Android Compatibility
Tools (Tool Reference)
- Application SDK
- Platform SDK
- Development tools
- Systems
Releases
Supporting Systems
- SSU
- Store

So - anything missing? Ideas, suggestions etc. (For 'new' topics/ideas reply as answers rather than comments - but then comments on these answers is fine to group ideas together)

edit retag flag offensive close delete

Comments

1

Shoot @Alex, you posted the same thing just before me :) Let me add to my request that for example SilicaListView should have a link to Qt Quick ListViews documentation instead of just "see the ListView documentation for its full list of available properties, signals and methods."

jollailija ( 2016-02-09 19:38:11 +0300 )edit

Okay, someone converted the comments to answers, but some contain the same thing- should we one answer per one suggestion and make a voting system or what? [edited by lbt: that would be me :) - it was a good point so I added a comment at the bottom of the question: For 'new' topics/ideas reply as answers rather than comments - but then comments on these answers is fine to group ideas together ]

jollailija ( 2016-02-09 20:07:40 +0300 )edit

2

This is a topic for the community meeting this Thursday February 11th 2016:

https://together.jolla.com/question/54157/sailfishos-open-source-collaboration-meeting-planning/

JSEHV ( 2016-02-09 23:07:42 +0300 )edit

2

What's the publishing site and its target audience? I'd rather post ideas knowing those first, please edit

reviewjolla ( 2016-02-09 23:10:53 +0300 )edit

This a really excellent project.

richardski ( 2016-02-10 17:14:27 +0300 )edit

4

answered 2016-02-09 20:34:04 +0300

lbt

6514 ●41 ●48 ●51

moderator

http://www.merproject.org...

I should have mentioned that this is also a topic for the community meeting in a couple of days:

https://together.jolla.com/question/54157/sailfishos-open-source-collaboration-meeting-planning/

edit flag offensive delete publish link

4

answered 2016-02-17 11:56:15 +0300

Jonni
1009 ●13 ●22 ●24

I read from the community meeting that the "Current plan is to use a wiki for most of the [documentation] material". I'd like to suggest to use GitHub hosted AsciiDoc or something similar as the master version of the documentation. Our company's open source product's documentation was recently migrated to such platform and it's working really nicely. We have good control over our documentation & easy way to prevent e.g. spam, but it's also easy for the users to contribute to the documentation.

See an example of end user facing documentation [1] with a link "Edit This Page"" -> forwards the user to GitHub [2] to do the editing and to submit a pull request [3].

[1] https://vaadin.com/docs/-/part/framework/advanced/advanced-embedding.html

[2] https://github.com/vaadin/vaadin/edit/master/documentation/advanced/advanced-embedding.asciidoc

[3] https://github.com/vaadin/vaadin/pull/43

edit flag offensive delete publish link

Comments

1

This is actually the approach I (much) prefer. It has a lot of technical benefits too. However the barrier to editing was felt to be a little too high.

lbt ( 2016-02-17 12:22:30 +0300 )edit

2

answered 2016-02-09 19:52:24 +0300

virgi26
4196 ●73 ●100 ●111

translations would be nice. User guide is only in english - it is not good at all

edit flag offensive delete publish link

Comments

1

Since they want input, should we post these things as comments or answers? Edit: Oh, and by the way- the guide is also in Finnish :)

jollailija ( 2016-02-09 19:56:50 +0300 )edit

2

Making the documentation translatable is an important part of the work

lbt ( 2016-02-09 19:58:20 +0300 )edit

2

answered 2016-02-10 02:17:13 +0300

This post is a wiki. Anyone with karma >75 is welcome to improve it.

updated 2016-02-10 12:19:14 +0300

r0kk3rz

10112 ●108 ●186 ●181

A "How to contribute guide":

lists various area where users/developers can help & how
how to send patches for review, how to help with testing, how to help with translations, etc.
list of agreeable open source licences to use

Feel free to extend. :)

edit flag offensive delete publish link

1

answered 2016-02-10 02:06:02 +0300

MartinK
18500 ●154 ●178 ●174

A guide about how to submit a Python application to the Jolla store.

There is already the Creating a Sailfish OS application in Python guide, but it only covers app creation, not how to get the app to the Jolla store.

So if we want people to submit (Python) app to the store, we should tell them how. :)

edit flag offensive delete publish link

1

answered 2016-02-10 02:13:49 +0300

This post is a wiki. Anyone with karma >75 is welcome to improve it.

updated 2016-02-10 02:13:49 +0300

MartinK
18500 ●154 ●178 ●174

Documentation about how to handle screen blanking control could be useful:

how to prevent the screen from going to sleep for apps that need this
- navigation systems, clocks, monitoring apps, etc.
how to blank & unblank the screen

Feel free to extend. :)

edit flag offensive delete publish link

Comments

nemo-keepalive is already reasonably well documented: https://git.merproject.org/mer-core/nemo-keepalive/tree/master

The issue is that the QML import is not harbour whitelisted, and so should jolla be publishing API docs for a non-whitelisted api?

r0kk3rz ( 2016-02-10 12:17:57 +0300 )edit

1

answered 2016-02-10 02:36:38 +0300

This post is a wiki. Anyone with karma >75 is welcome to improve it.

updated 2016-02-10 02:39:28 +0300

MartinK
18500 ●154 ●178 ●174

A "How to report bugs" guide:

what a good bug report should contain
different kinds of bug reports & where should they go
- bugs in core components & middleware -> Mer bugzilla
- bugs in the closed UI and closed default apps -> Together (?)
- bugs in third party apps -> upstream issues trackers (usually Github issues), support threads, etc.
- bugs in community ports -> #sailfishos-porters IRC channel & xda forum, TMO threads, etc.
- localization bugs -> ? (l10n bugs posted on Together seem to be summarily ignored)

Feel free to extend! :)

edit flag offensive delete publish link

1

answered 2016-02-10 02:38:54 +0300

This post is a wiki. Anyone with karma >75 is welcome to improve it.

updated 2016-02-10 02:38:54 +0300

MartinK
18500 ●154 ●178 ●174

A "Developping apps with SDL2" guide that covers Sailfish OS specifics of SDL app development (with links to general SDL development resources) & SDL app submission to Jolla Store.

SDL2 is available & allowed in the Jolla Store, but quite buggy and undocumented. So a proper SDL2 guide could certainly help.

edit flag offensive delete publish link

1

answered 2016-02-10 14:56:58 +0300

lakutalo

20555 ●168 ●261 ●264

updated 2016-02-10 15:07:42 +0300

Object Maps
to interactively navigate/dive into APIs (by using URL links), showing references of all the different object models, both graphically and as written short documentations (parameters, code example, etc.)

edit flag offensive delete publish link

0

answered 2016-02-09 18:38:34 +0300

ApB
27604 ●302 ●421 ●409

The user guide will be better if it is a video. Or a series of videos. No user reads docs.

edit flag offensive delete publish link

Comments

4

Wrong. A document allows me to read at my own pace and skip randomly.

A video forces me to proceed at the author's pace.

Besides, how do you intend to video document an API?

pichlo ( 2016-02-09 21:48:57 +0300 )edit

@pichlo i was refering to the user guide (third bullet) not apis and dev stuff.

ApB ( 2016-02-10 00:29:12 +0300 )edit

What should SailfishOS documentation be providing?

Comments

23 Answers

Comments

Comments

Comments

Comments

Question tools

Stats

Related questions

What should SailfishOS documentation be providing?

Comments

23 Answers

Comments

Comments

Comments

Comments

Question tools

Public thread

Stats

Related questions