add help page #4405
add help page #4405
Conversation
|
Hm, the only issue I see here is that having English screenshots with translated text could get a bit weird. Though I'm a bit puzzled what could be a nice solution here. |
|
Um, the text and images here are taken from the 'getting started' tutorial series which is going on to the diasporafoundation.org site. Two points:
|
|
|
@MrZyx I think I found a nice solution for the English screenshots: (just a draft) This gives the user an impression how the website will look like but we don't need any text. |
Moreover diasporafoundation is not translatable (yet?). But I think having a whole tutorial in the pod is maybe too much, I'd prefer to see something like a FAQ |
Actually, thanks to @MrZyx , it is translatable as of an hour ago - see #35 on the project site repo. |
|
@goobertron and @Flaburgan suggested a FAQ (goob did that on loomio) so I updated the screenshot in the description. At the moment the code for the FAQ is not on github. |
|
@svbergerem that's really nice! |
|
I really like your design, and I think something in that format would be a really good addition to pods. |
|
Alright because of the positive feedback I continued working on the FAQ and used Wiki: FAQ for Users. I updated the screenshots and the code in this PR. |
| get 'help/faq/mentions' => 'help#mentions', :as => 'mentions_faq' | ||
| get 'help/faq/resharing_posts' => 'help#resharing_posts', :as => 'resharing_posts_faq' | ||
| get 'help/faq/account_and_data_management' => 'help#account_and_data_management', :as => 'account_and_data_management_faq' | ||
| get 'help/faq/miscellaneous' => 'help#miscellaneous', :as => 'miscellaneous_faq' |
There was a problem hiding this comment.
Have a look at scope to reduce the repetition here a bit, note the path, controller and as options there. You should be able to reduce the individual route definitions to something like get :aspects with that ;)
There was a problem hiding this comment.
Thanks, done. I have never worked with rails before and just looked up how to define routes so I already expected that one could improve that.
|
By the way, I'm not really keen on the screen shot with the text redacted. It looks as though it's been censored. And in many cases, a screen shot with the text redacted won't be very useful. I'm not sure what the solution is, unless an image folder for each language can be added to /config/locales/ and image links directed to the appropriate folder. |
|
Well, we surely could include screenshots for all languages, it's just that maintaining those would be a pain in the ass. |
|
Well, the interface does not change everytime... |
|
We would need to track all changes in the translations as well, occasionally translation teams decide to change a terms translation. Having screenshot with the old terms would be just as confusing as having the English translation only. |
|
By the way we will have the same problem on diasporafoundation.org where the translatable tutorials actually use screenshots. |
|
Is there anything on the technical part which needs to be done? I'd like to see this in the next release so I will ask on loomio if someone could read the FAQ and correct errors / add important things. |
|
Nothing serious, no, personally I'd probably avoid the repetition in the views by defining some sort of Hash/Array thing for the translation keys to iterate over, but that's nothing I'd enforce. |
|
I am not able to do that on my own and IMO this solution gives us the possibility to add images, create lists and so on. (but I have to admit that I already thought of that ;) ) |
|
@svbergerem Loving how this looks! :D |
|
Steffen, do you want me to edit the FAQ on the wiki, or another copy? |
|
@goobertron If you think that the changes are meaningful on the wiki too then just change the FAQ on the wiki and tell me when you think you are done. After that I will look at the changelog(s) and do the same changes in this PR. |
|
Steffen, I'm afraid I don't think I'll be able to properly edit that FAQ text before 27 Aug. I've started, but I really need to focus on other things and also take some rest. Sorry about that. |
|
@goobertron No problem. Do you think the FAQ is good enough to merge this PR? I read the FAQ and found no obvious mistakes. |
|
Well, there are links to Diasporial, which will become outdated when the new tutorials pages are merged to the project site (which should happen on the same day 0.2.0.0 is released), a recommendation to sign up to diasp.org, which is already a mega-pod, and that's just in the first couple of paragraphs! The problem with releasing this text to individual pods for them to customise is that it'll be hellishly difficult to update text after the first release, so we'd better make very sure it's absolutely correct and up to date at the start, which that FAQ for users page on the wiki certainly isn't, from my brief glance at it. So I'd say don't merge this PR with the current text from that page, no. Sorry. |
|
@goobertron I changed the link to Diasporial into a link to the new tutorials and removed the "how do I join/find a pod?" questions so there is also no recommendation of diasp.org. (should have mentioned that earlier) When a podmin changes the FAQ in his installation of diaspora* he will get a merge-conflict in the next update if we also changed the section. Then it is his decision if he wants to keep his own version or if he wants to adapt it. IMO the FAQ don't have to be perfect but they shouldn't contain big mistakes. |
|
about the issue with language in the interface vs. screenshots: how about showing the localized text and in brackets the english original. (we could style them somehow so it becomes obvious, or add a tooltip/abbr) |
|
IMO that sounds good. I think we should discuss that on loomio because there are no screenshots included in this PR and we will have to decide how to handle that issue when translating the tutorials (diaspora/diaspora-project-site#44) |
|
I personally think that if there are screenshots, we are closer to a tutorial than to a FAQ... |
|
So what's the status on this, include in the release? I guess it's fine from @svbergerem's side, it would be fine by me too. @goobertron do you still have any concerns? |
|
@MrZyx Yup, I don't want any big mistakes in the FAQ but I didn't find any. @goobertron changed some things in the FAQ on the wiki yesterday but the related questions are not included in this PR. |
|
I'm going to try to edit the FAQ page today just to catch any major out-of-date things. Will that be ok for you @svbergerem ? I don't think we should hold this up just because the text is not completely edited. If it has links to the wiki and the new tutorials in this help section, people will be able to find the best information even if it's not all covered in the text in this PR. If you can give me until late afternoon/early evening, I'll supply some edited text. Hopefully before then. |
|
@goobertron: late afternoon/early evening in which timezone? ;) UTC+2 is mine. |
|
All done. Hope it's all fine for you. Have updated a lot of 'alpha' stuff that had been there for a couple of years and is now out of date. Don't know the current situation about RSS feeds, so haven't updated that - you might want to look at it: https://wiki.diasporafoundation.org/FAQ_for_users#Can_I_subscribe_to_someone.27s_public_posts_with_a_feed_reader.3F There's a lot of duplication with the tutorials and other guides we have. I think in future it would be worth having a complete rethink of this FAQ, and of the help section to be included in pods as part of this PR. But at least I think all the information is now up to date and correct. Hope that helps. |
|
Where was the link to this page added? |
|
@goobertron Ok, I hope I got all your updates. @Flaburgan In the user menu is a "Help" link |
|
Oh, I just thought, if this is being merged for this release I'm going to have to update the tutorials with reference to this. I don't really have the energy at the moment, hopefully we can get away with it for a while, or someone else can correct it. It'll be in part 2, 'The interface', where it lists everything in the black bar. I don't think it'll need to be mentioned elsewhere, although you might want to go through and check. Actually, on second thoughts, might be best to wait until this PR is live so I can see how it looks in the user menu. I'll do it after this version is released 0.2.0.0. |
|
Alright, thank you everybody! |
|
Thank you @goobertron, you improved a lot of stuff in the FAQ. |
|
@goobertron I have no idea how I can thank you for all the energy you put in all these texts, thank you very much! If I meet you IRL, you got a beer! (And of course thanks to everyone who integrate it, especially @svbergerem for this one) |
|
Thank you everyone for your kind words. @svbergerem , was the revised text OK for your help page? I see this PR has been merged, so I guess so! We can always work on a new version of the text later if you'd like to. |
|
@goobertron Tbh. I don't have that much time today so I didn't read everything you changed but the things that I read were really good. I'd say we should wait for some reactions of users to this FAQ and then see if there is anything we should improve. All in all I am quite happy about the FAQ we got right know. |
|
@svbergerem That's a very good idea, to wait and see what users say. I'm glad I could help a little bit, and thanks for creating a feature which will help people to get the most out of diaspora. If you want any help with changing or adding to the text in the future, you know where to find me :) |
This is a draft of a new help page:
loomio discussion