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

21

answered 2016-02-09 19:37:39 +0300

jollailija

4736 ●74 ●115 ●129

https://jollailija.github...

Screenshots of the Silica components would be really great! Also, the Silica Reference does not list all the possible properties of some components. Take for example the SilicaListView, which inherits many things from Qt Quick ListView that aren't listed here. SilicaListView is not a great example since the name hints clearly where to look for documentation, but some of the components aren't that obvious.

edit flag offensive delete publish link

Comments

1

Also there are various bugs in the reference documentation, like wrong property types.

MartinK ( 2016-02-10 01:56:23 +0300 )edit

12

answered 2016-02-09 19:33:33 +0300

Alex

10635 ●181 ●247 ●252

That's great that you are trying to enhance the documentaion now. :)

For the documentation of UI components the documentation should really provide a screenshot/picture of every UI element so that you are aware of what the documentation is talking about (especially handy for developers unfamiliar with SFOS).

The documentation should also be much more specific on which properties are needed for the UI components.

Another thing is that you should be able to find the documentation you need so the documentation should be e.g. linked on a better place on jolla.com.

edit flag offensive delete publish link

10

answered 2016-02-09 23:55:08 +0300

jollajo

2453 ●52 ●83 ●87

Though I'm not a developer I'd love to experiment with QML-UIs in combination with DBUS calls to the OS and installed services. From other people told me you need to install a dbus monitor and reverse engineer existing dbus-interfaces.

A reference documentation on the standard DBUS interfaces would be helpful.

edit flag offensive delete publish link

Comments

2

+1 For example: (amongst many others) how to make a call, how to get contact list, how to get music list, how to play music and how to get the currect state of the flashlight, turn on/off gps, turn on/off bluetooth...

rgrnetalk ( 2016-02-10 00:00:45 +0300 )edit

2

Agreed. Documentation on such software would be ideal. You don't install dbus-monitor, you type that into terminal and hit enter, then the monitor spews dbus actions into terminal window as you do stuff with the phone. Dbus is part of freedesktop,org, it isn't specific to Sailfish. There is quite a bit of info here on TJC regarding usage of Dbus commands. A quick example on usage of dbus; https://together.jolla.com/question/93285/starting-and-stopping-tethering-via-the-command-line/

In terminal on your Jolla, type in dbus-send --session --print-reply --dest="org.freedesktop.DBus" /org/freedesktop/DBus org.freedesktop.DBus.ListActivatableNames

This shows you a list of activatable DBus interfaces/services. Some are already implemented by Jolla, others are waiting to be found. Again, agreed, some clear documentation would be great!, but don;t hold your breath. The same goes for Ambience and TOH's - all fallen by the wayside.

Spam Hunter ( 2016-02-10 01:08:55 +0300 )edit

a lot of these arent 'publicly consumable apis' yet, the sailfishos documentation should really only apply to harbour allowed apis

r0kk3rz ( 2016-02-10 12:22:55 +0300 )edit

@r0kk3rz: Well, dont thing it is that simple. While the offical docs should certainly target primarily application development for the Jolla Store, I can see cases where you would include APIs not yet ready for the Store (of course always clearly marked as such):

APIs that schould become stable in the near future - so that developers can start preparing their aps for the new possibilities
new/not yet stable APIs - so that they can be tested in real conditions by non-Store apps, which could make the final API design much better than a design set in stone withou real world feedback
- thats basicaly the reason why Qt sometimes releases new modules first as a tech-preview

MartinK ( 2016-02-10 20:24:47 +0300 )edit

9

answered 2016-02-09 21:51:11 +0300

lakutalo

20555 ●168 ●261 ●264

I do not know if this is already covered by the list of yours, but I think it would be great to get comprehensive documentation also on specific modules like

ngfd
quickactions
URL handlers
LED patterns
BT configuration
Cross-compiling of existing projects for Jolla/armv7hl

edit flag offensive delete publish link

Comments

3

+1 for quickactions and how to package them into harbour app (or is it not allowed?)

rgrnetalk ( 2016-02-09 23:57:54 +0300 )edit

8

answered 2016-02-09 21:52:56 +0300

lakutalo

20555 ●168 ●261 ●264

Please provide lots of example code to quickly get hands-on.

edit flag offensive delete publish link

Comments

1

Yes! Plus: Examples, examples, examples!

ossi1967 ( 2016-02-10 15:12:10 +0300 )edit

2

As someone who prefers to learn by doing, I couldn't agree more. A few minimal sample/skeleton apps that can be used as a starting point will be a great help in getting started with app development!

Lomax ( 2016-02-10 16:10:25 +0300 )edit

7

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

peter-berlin

1020 ●21 ●27 ●33

@ApB ...why not video and docs!?! I am one of the (old fashion) guys, who read docs :-)

edit flag offensive delete publish link

7

answered 2016-02-09 21:12:13 +0300

otsaloma

806 ●8 ●15 ●17

https://github.com/otsalo...

I'd like to see more of the common pitfalls and, more broadly and conversely, design best practices or human interface guidelines or UX patterns or whatever it's called these days. When I look at the applications released at Harbour or OpenRepos I see wildy different layouts, styles, design etc., some of which are outright bad, and some developers just unware of little things like SearchField.textLeftMargin or the various Theme constants.

edit flag offensive delete publish link

7

answered 2016-02-09 21:43:17 +0300

tortoisedoc

11414 ●172 ●269 ●287

http://kastlunger.blogspo...

updated 2016-02-10 10:08:36 +0300

Architectural references; as in pictures :)

more coverage of the platform features, even the less developed ones (perhaps a grading to evaluate stage of development, like draft/beta/verXX)

do not leave all to the developer ("there s the source go look it up " is a very lame excuse for lavk of docunentation)!

Also, please do not deviate from the SFOS peculiarities; I see no sense in collecting documentation about general linux knowledge, for instance.

edit flag offensive delete publish link

6

answered 2016-02-10 02:01:09 +0300

MartinK
18500 ●154 ●178 ●174

What about the inevitable documentation bugs ? I think there needs to be a robust way of reporting documentation bugs so that they can be actually fixed.

Or even better - a way to send documentation fixes (docs on wiki, sending pull requests with docs fixes, etc.).

edit flag offensive delete publish link

Comments

1

Couldn't agree more ! Apart from fixes, it could be nice if the community could add some code examples and some tips and tricks too.

François ( 2016-02-10 11:28:15 +0300 )edit

5

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

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

updated 2016-02-10 02:10:25 +0300

MartinK
18500 ●154 ●178 ●174

Documentation about how to work with the wakelock/powersaving system on Sailfish OS would be useful:

how to prevent the device from going to sleep for apps that require it
how to schedule wakepups for apps that need to perform periodic tasks

Feel free to extend. :)

edit flag offensive delete publish link

What should SailfishOS documentation be providing?

Comments

23 Answers

Comments

Comments

Comments

Comments

Comments

Question tools

Stats

Related questions

What should SailfishOS documentation be providing?

Comments

23 Answers

Comments

Comments

Comments

Comments

Comments

Question tools

Public thread

Stats

Related questions