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

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

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

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

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

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

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

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

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

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