search

openpaperwork / paperwork

Personal document manager (Linux/Windows) -- Moved to Gnome's Gitlab
https://gitlab.gnome.org/World/OpenPaperwork/paperwork
2.43k stars 149 forks source link

Onboard users #563

Closed mjourdan closed 7 years ago

mjourdan commented 7 years ago

In ticket #548, we saw the following issues:

So I made a mockup to onboard user with a first paper. Thoughts?

jflesch commented 7 years ago

Hm, interesting idea. Just wondering, how do they get this "man page" again later ? An option "help" in the menus somewhere ?

tYYGH commented 7 years ago

@mjourdan Very good ideas (manual document, stick 1st doc to bottom in list, etc.)! @jflesch This document may very well be a real document, copied-pasted from /usr/share/paperwork/… on the fly when Paperwork is launched on an empty/inexistant documents folder, or when Paperwork is switched to such a folder in the config panel. Then the user could read it whenever they want just like any other document, and ultimately delete it when they decide they understand everything.

jflesch commented 7 years ago

Good point. Now the problem is to define the content of the document

mjourdan commented 7 years ago

@tYYGH thanks, I found nice sources of inspiration during my last vacations ;) In addition to what @tYYGH described, we could eventually use the same trick each time user presses the "help" menu entry, or to show the release notes when a major release is installed...

@jflesch FYI the unreadable text I used as an example in the mockup is not (total) crap. I resized a bit the mockup but my laptop crashed before I could push my changes. I'm too lazy to turn it on again, but you can take a look at the .svg with inkscape if you are curious.

jflesch commented 7 years ago

BTW, this document would have also to be translated. The correct version would have to be picked based on the system/user language.

jflesch commented 7 years ago

I have a feeling it will end up being a very big document, therefore #76 will become handy :-)

Also, as a user, I tend to delete really quickly this kind of document --> how to get it back ? Possible idea: Application menu --> "help" : would (re)open the document, but not show it in the document list.

jflesch commented 7 years ago

Topics that must be detailed:

(edit: will be for the complete manual only, see #573 )

Do you see something missing ?

(I also really really like this idea of a first document because it solves an issue I've had for a very long time, which is how to integrate nicely a documentation inside Paperwork :-)

I wonder, maybe I could push the logic a little bit further, and also add in the menu "advanced" a "contributor handbook" (for translators, testers, code contributors, etc) ?

jflesch commented 7 years ago

show the release notes when a major release is installed

Oh nice idea too ! :-) (documents, documents everywhere !! :-D )

jflesch commented 7 years ago

@mjourdan BTW, thank you for the base content. It's really interesting for me, because it also gives me the perspective of someone else using Paperwork :-)

jflesch commented 7 years ago

Work in progress: https://github.com/jflesch/paperwork/blob/unstable/doc/usage.pdf

mjourdan commented 7 years ago

I like the illustration on your wip! I think it would better fit at the end of the document though, in the "let's start" part. For the beggining, I would see something more static, to say "welcome, take your time to read this".

Which make me think this very first paper purpose is to onboard user, it is not to harass them with the complete list of features described in details. This confusion is my entire mistake, as I talked about "man pages", which could indeed use a table of content, but should definetely take place in a separate documents. We should split to a separate issue for that, shall we?

Regarding the contributor handbook, I have a feeling "advanced" should be kept for rarely used actions. For documentation, I would organize stuff like this:

jflesch commented 7 years ago

Good point, I guess I can easily make 2 documents. One introduction, and one being the complete manual.

What I have in mind:

BTW, I was wondering : is it useful to display the manual at the bottom of the list as shown in your mockup. From a technical point of view, it will be pretty annoying to do, and I don't see the point in making this document any different from other documents ?

mjourdan commented 7 years ago
  • When the user starts Paperwork, if their work directory is empty, they get one first document : the introduction to Paperwork (which they can safely delete). One of the advantages for new users is that this document can be used for experimentations.

OK.

  • In the application menu, I can add a sub-menu "help" (besides "advanced"), with the items you listed. Clicking on one of them will open the corresponding document, but not add it to the work directory / document list.

How would it open, then? Would it open in a modal window or something else? Showing the page in the left part without making it appear in the left pane could be a bit surprising. Perhaps the document could disappear from the list (as if the user pressed "delete") when user switches to another paper?

BTW, I was wondering : is it useful to display the manual at the bottom of the list as shown in your mockup. From a technical point of view, it will be pretty annoying to do, and I don't see the point in making this document any different from other documents ?

The idea was not to have different behaviors for different documents. It is to replace the current behavior (stick to top) by a new one (stick to bottom), so that when the user will add a second, then a third paper, she willl understand the oldest papers are at the bottom of the list. Just thought this would be more easy to understand than the latest paper pushing down the previous one. If it makes things too complex, this is no big deal anyway.

jflesch commented 7 years ago

Work in progress : https://github.com/jflesch/paperwork/blob/unstable/doc/intro.pdf (usage.pdf will be the full manual for #573 )

How would it open, then? Would it open in a modal window or something else?

Application menu -> "Help" -> "Introduction" + Application menu -> "Help" -> "Manual" : Both would appear like any other document in the right pane. It wouldn't change the document list at all.

jflesch commented 7 years ago

intro

^ I was thinking of using this drawing as the first illustration in the document "Welcome aboard / Introduction" (it would be inked first of course). For me, it looks fitting to the first paragraph. Do you think that could work ?

mjourdan commented 7 years ago

I like how the flying sheets announce the paper plane at the end of the pdf! I think it illustrates well the first paragraph, but not sure it could work. Maybe putting a hand up to say hello could help make things a bit warmer? This could mean the person pictured is not a lambda user (as she says hello) but yourself, welcoming new users. I don't know if I'm full of bullshit because I'm tired but hey, why not!?

jflesch commented 7 years ago

Well, I use Paperwork, therefore I don't have huge messy piles of papers progressively destroyed by the wind/simple draft ;)

jflesch commented 7 years ago

intro svg

jflesch commented 7 years ago

IMHO, the introduction document is ready: English : https://github.com/jflesch/paperwork/raw/unstable/doc/intro.pdf French : https://github.com/jflesch/paperwork/raw/unstable/doc/intro_fr.pdf (it may need some re-reading).

tYYGH commented 7 years ago

The French document has English screenshots; apart from that, it is a good introduction, with a subtle humoristic touch. About the above picture, I just do not get the meaning… What is the intended message?

tYYGH commented 7 years ago

intro-with-notes.pdf Now the English document. I added some notes where the sentences seemed wrong to me; keep in mind that I’m French too, though ;-) I only wrote notes for the most obvious things. Some sentences I wouldn’t have written quite this way… but they may still be OK so I said nothing…

jflesch commented 7 years ago

The French document has English screenshots

Right now, doing all the screenshots in all the languages will be too much work. 1.2 will be released like that. Later, since I've automated some of the screenshots, I'll try to make them in each language. But even then, some will remain in English.

About the above picture, I just do not get the meaning… What is the intended message?

It's supposed to be related to the first paragraph :/

jflesch commented 7 years ago

There are very good catches in your notes (There are also some minor points where I disagree). I've updated intro.pdf accordingly.

Just out of curiosity : which software did you use to add notes ?

jflesch commented 7 years ago

By the way, if you have any other idea for the first illustration, I'm interested

mjourdan commented 7 years ago

Well, I use Paperwork, therefore I don't have huge messy piles of papers progressively destroyed by the wind/simple draft ;)

That was my point, a bit of storytelling: you made paperwork to solve this problem, and breeze is not an ennemy anymore.

Details:

"Tell us", in the very last sentence, should be a link or an e-mail adress pointing where you want, so that user can easily give us feedback.

Are you sure about the font?

jflesch commented 7 years ago

figure 2 is too low

Fixed

figure 3 should have screenshots of the same size

I'm automating most of the screenshots. I've centered them around the mouse cursor, so it's actually not trivial to fix. Anyway, I guess it will be good enough for 1.2. We can fix that later.

"Tell us", in the very last sentence, should be a link or an e-mail adress pointing where you want, so that user can easily give us feedback.

Actually, they already are, but I guess it ain't obvious. --> fixed

Are you sure about the font?

That's the default Lyx/LateX font. It seemed fine to me so I didn't change it. Any font you would prefer ?

tYYGH commented 7 years ago

@jflesch The software is simply evince ;-) I’m a Gnome3 user… these days.

tYYGH commented 7 years ago

rel. picture. I now see why I did not understand it.

The way I see it, a big pile of paper is what I have now, when using Paperwork, and that’s OK because this big pile is stored to be almost never retrieved again. When I need a document, I go to the computer instead.

What I had before was rather: 1º many labelled folders so that the many papers are mostly sorted, in case I need to retrieve one; and some of these folders got so big, so fast! 2º cardboard boxes where I archived the contents of the folders when they got too fat; but these boxes where so hard to get to, hidden behind a layer of dust… 3º several smaller piles of paper scattered around the flat, each pile a number of papers that I intended to: — take care of, soon… and papers got forgotten, and payments got late, and so on; — or put in the right folder, as soon as I made room inside, which would happen as soon as I found the time to transfer the old contents in the cardboard boxes.

In short, I used to get the feeling that I lived in Gaston Lagaffe’s late-mail room, and now I just have this one big stack (conceptually)… and the computer!

jflesch commented 7 years ago

39dc67a6c27ec8d1e5caf9c5038388d8b584da3f ^ When Paperwork starts, if the work directory is empty, it will automatically import the introduction doc, and apply a new label "Documentation" to it.

jflesch commented 7 years ago

The software is simply evince ;-)

Oh, I didn't know Evince could do that. Good to know :)

I forgot to indicate this commit on this ticket : f93c05b69a470797fdddb0c2b5f5eb8ea749c954

Currently, it looks like that :

paperwork_integrated_help

jflesch commented 7 years ago

As the feature has been implemented, I'm going to close this ticket. However, if you still see anything that should be changed, feel free to comment here again and I will reopen this ticket.

jflesch commented 7 years ago

32895b2834b53d23e8dd94ba893a4903c6c2b530

jflesch commented 7 years ago

Re-read by an Australian friend of my girlfriend : a74b681372d51658bb8e1a83e519211998a1fc78