Ask / Submit
37

What should SailfishOS documentation be providing?

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

lbt gravatar image

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

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 +0200 )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 +0200 )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 +0200 )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 +0200 )edit

This a really excellent project.

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

23 Answers

Sort by » oldest newest most voted
4

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

lbt gravatar image

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 more
4

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

Jonni gravatar image

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 more

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 +0200 )edit
2

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

virgi26 gravatar image

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

edit flag offensive delete publish link more

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 +0200 )edit
2

Making the documentation translatable is an important part of the work

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

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

this post is marked as community wiki

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

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

r0kk3rz gravatar image

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 more
1

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

MartinK gravatar image

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 more
1

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

this post is marked as community wiki

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

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

MartinK gravatar image

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 more

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 +0200 )edit
1

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

this post is marked as community wiki

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

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

MartinK gravatar image

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 more
1

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

this post is marked as community wiki

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

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

MartinK gravatar image

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 more
1

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

lakutalo gravatar image

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

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 more
0

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

ApB gravatar image

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 more

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 +0200 )edit

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

ApB ( 2016-02-10 00:29:12 +0200 )edit
Login/Signup to Answer

Question tools

Follow
9 followers

Stats

Asked: 2016-02-09 17:46:57 +0200

Seen: 1,635 times

Last updated: Feb 21 '16