Having and Maintain a good user documentation

asked 2015-07-21 12:19:40 +0300

cemoi71 gravatar image

updated 2015-07-21 13:28:23 +0300

Dear jolla team and managers,

I know you have many things to do, and you are really creative and productive. That's is not to criticize. That's great.

And there is a big part that i find that is something lost of sight. You can correct me if it's not. There is a lots of thing which are done, and not really documented. The user guide is for me currently not good enough.
I don't know for the 3d part interface for the developer part.

Documentation is the a and o by software developing.
software is nothing if it's not documented.

Everywhere i see that function x is integrated, every where i see different way to use it.
There is an app in harbour too or a gui from sfos, and it is pretty hard sometimes to have access on the info how to do it...
Because it is not in user guide, because there is many tjc threads that are no more relevant. We should make a lot of search, cross all infos with the version of each found topics.

for example I needed more than 2h to find how can i start tethering with which possibility (usb/bl/wifi) It awful!!

Please keep in mind that developing is not just programming, but take the documentation in charge too. By planning a new function or improvement, the dedicated documentation should be in timing calculation. I don't know if it's done in this way. And if not please that is really suggested.

Please after every release of functions take time to document it! at last the user guide.
I think more effort should be done, maybe more human resources.
This is really important, a good documentation make a good impression and make software clean!

If you want to maintain your update plan, and this request would disturb it.
You could make an Update plan a la Intel. A tic-tac update plan.
A tic with a lot of new or improved functionalities (user documentation updated) with major-bugfixes . And then a tac as just many bugfixes (documentation is just related to bug).

Thank you in advance for thinking about it.

Have a good sail

edit retag flag offensive close delete



There is separate post about documentation in here => https://together.jolla.com/question/13280/whats-missing-in-the-user-guide/

Kari ( 2015-07-21 12:27:24 +0300 )edit

@Kari i'm sorry but it is not the same. my thread is to put the documentation priority much higher.
the thread that you have references is a request on what it is missing.
That is a big difference

cemoi71 ( 2015-07-21 13:08:02 +0300 )edit

I don't think that a great user guide. The basis maybe is good (can't really estimate it). but a lot's of things are missed. in this aspect even if the basis good or not, a user guide can not be good if a lot's of things are missed. never!!!

cemoi71 ( 2015-07-21 13:15:18 +0300 )edit

I agree, especially on the software side. developing is pain, when you have to go through mailing lists, wait answers on IRC, try to figure out which parts of the official Qt documentation works on SFOS and which parts not. The current developer documentation is a mess (only silica components are somewhat well documented), and I think that any developer looking at this platform, unfamiliar to it, probably think it is a mess. It is maybe easy for someone who has years of experience developing for N9 and others, but anyone coming from desktop Qt or anywhere else will be very frustrated.

Acce ( 2015-07-21 18:43:40 +0300 )edit

@Acce thank you to bring your experience. Cool!
Need help to improve the thread.
i have no idea for the software dev side, that's why i didn't notice it clearly for it.
Maybe one day i'll try to develop something, and i will know the stand. Currently i can't (have no time for it).
Maybe you can add a clear notification on main thread (i have no problem with it), i can do it too but it will be as a general remark (can't bring some facts).
Or you can convert your remark as answer.
What do you think of it? have you got any suggestion too?
Every further experiences are welcome.

cemoi71 ( 2015-07-21 19:23:06 +0300 )edit