search

ipfs-shipyard / ipfs-share-files

Share files via IPFS
https://share.ipfs.io
MIT License
149 stars 31 forks source link

App copy and assets #41

Closed fsdiogo closed 5 years ago

fsdiogo commented 6 years ago

As discussed in the @ipfs-shipyard/gui weekly sync, the app copy needs to be updated.

In the first pass of this I got some copy from the ipfs.io website, but it's too vague for this case and doesn't explain what really happens when you add or download files.

As this app can be used as an entry point to non technical users, what happens should be clearly described.

Feedback is greatly appreciated 😇. I'll update the bullets below as we reach an agreement of what should be in the copy or not.

Add page

Download page

lidel commented 6 years ago

(Reposting relevant parts from https://github.com/ipfs/ipfs-gui/issues/34#issuecomment-373926710)

Not sure in what order, but there should be some info about data availability:

  • a brief explainer that public gateway does not guarantee availability of content after X hours
    • main reason: we need to be explicitly honest about gateway not keeping files forever, so there is no negative UX when not pinned content disappears from public gateway next week
    • secondary reason here is nudging users to install IPFS and pin content they care about to stay available for longer

It could be used as an opportunity to explain what IPFS is and how to take advantage of its powers:

  • short explanation of IPFS
  • a call to action to install IPFS so that user can
    • share with peers without needing any intermediaries
    • pin files that should be available longer that the time offered by public gateway

cc @olizilla

olizilla commented 5 years ago

@terichadbourne is this something you could help us with?

terichadbourne commented 5 years ago

@olizilla I can spend a little time checking whether content is comprehensible by yours truly on behalf of "normal" humankind, but it would be helpful if you all could first draft whatever revised copy covers the concepts you want included so I'm going off of that and then telling you what I can't understand and proposing alternate wording where I'm able or asking questions where I'm extra lost.

I'd also need more context around what pre-existing knowledge you expect from your users. Do they know nothing about P2P? Know about P2P generally but not IPFS? Did they all get redirected here from the same website so whatever content is there can count as pre-existing knowledge? Do they have IPFS installed somehow already?

olizilla commented 5 years ago

Ok so, here is a copy proposal. I want to focus on what the person needs to do to use the share service, and explain the details of IPFS that are most relevant to helping them decide if they should use this service or not.

Share files directly from your device

  1. Add your files Anyone you give the link to will be able to get the files. Don’t add sensitive or copyrighted files.

  2. Send the share link IPFS gives the files a unique fingerprint called a CID that is used to find them again on the network.

  3. Keep this page open You are sharing the content from your device. Your friends can help you co-host the content by also keeping share url open in their browser.

If we detect that we're using an external IPFS daemon via the api then the 3rd point should change to

  1. Leave your IPFS daemon running

Here is a mock up:

share--icons-left

and a couple of icon placement variations as I'm just not sure which one looks best

indented inline
share--icons-indent share--icons-inline
fsdiogo commented 5 years ago

I like it, I was afraid it was going to have loads of copy. We need this short and sweet so people actually read it.

I think it would be cool to mention that when you add a files, the hash you get is actually the files content, or at least link that info somewhere.

That copy must change in the download page.

terichadbourne commented 5 years ago

I'm playing with the site for the first time as a sharer in Chrome and a receiver in Firefox and want to share what I find confusing or explanation-worthy in case it affects the copy you want to include.

I added one file in Chrome, copied the link, and opened it in Firefox where I see the download button for that one file. When I added another file, there was nothing noticeable to indicate that the URL had changed and that I'd need to send it to my friend again if I wanted them to have access to both files. In the receiver's window they still just have the first file. I also don't see a way to go back and get a URL for just one of files if I only want to share one of them instead of the whole current batch. Is that possible and I'm missing how to do it? (Only because I have some background in CIDs do I understand why this is probably happening at a folder level with a changing link.) I'd recommend adding some text as soon as any subsequent file is added to note that the folder URL has changed, and also making the links for individual files available by clicking next to them if that's an option. Alternatively, you could preemptively add some text to the effect of "Sharing multiple files? Wait until you've added all of them to share the link, which changes as you change the contents of your folder." Regardless of how it's handled, I think the changing CIDs need to be addressed if you're going to allow more than one file shared at a time. Step 2 is one place you could do this.

As a receiver, my expectation is that I can click on the "Download All" button to download all shared files or click on the individual icons to download a single file. None of the buttons appear to work. The individual buttons flash and the "Download All" button changes to "Downloading" with a gray circle next to it, but there's no pop-up like I'd normally see in my browser and nothing new in my downloads folder while in Firefox. Where should I find the downloaded files? Or do they just download so slowly that I'll give up before receiving them? In Chrome, the individual icons work with my system dialog but the "Download All" button doesn't work in the same way described above.

As a receiver, it might be nice to have some clickable text or a button leading me to where I can share my own files if I'm liking this system.

There's not much visual distinction right now between a sharing screen and a receiving screen. If you think people are going to leave these windows open and use the service, a clear visual distinction would help people who have one sharing tab and one or more receiving tabs open. I agree with @fsdiogo that if you're switching to step-based language, you can't keep the same wording on the download page as on the sharing page.

I would have expected URL to be capitalized.

Like @fsdiogo, I'm impressed with how short @olizilla's copy is, and I like that it's focused on the steps you need to take. However, if you'd like to consider giving more background without crowding the screen, you could add some "How it works" type links that let you expand to show an additional sentence or two about how CIDs actually work.

One thing I'm curious about as a user is whether I only need to have my window open in the browser or also need to have my normal internet connection working. Does one of the people need to be connected to the normal internet at all times, or are you opening a doorway to a secret portal that lets this work offline? If the latter, that's a benefit that's worth calling out in step 3.

FWIW, I don't think "normal" people know what the word "hypermedia" means, which appears to be a key one in the tagline. Also, because you've chosen to focus on steps to take here, there's nothing to support that tagline and show that IPFS "makes the web faster, safer, and more open." Do with this what you will. :)

terichadbourne commented 5 years ago

One more quick thing. On the current live site the sharing box says "If no other nodes pin your files and you stop serving them, they will disappear from the network." With @olizilla's current copy proposal, the word "node" isn't introduced anywhere, so this text would need to be simplified to be about other people keeping their browser windows open, if it's going to still be here at all.

olizilla commented 5 years ago

The app should work. You should be able to download things. It may be taking a long time to find the files, or it may be a bug. if it's "taking a long time" we need to add an indicator ot the UI.

The proposed copy is for the person adding the files. I think we could offer up roughly the same set of steps but re-framed as "here is what happened"

I like the idea of adding a section below that calls out some of the fundamentals of how IPFS works, a little like the website does in the How section https://ipfs.io/#how

I would have expected URL to be capitalized.

I switched it to share link in the copy and the other images. I think that's simpler. I agree if we go with URL it should be capitalised. @terichadbourne do you have a preference for share URL or share link?

One thing I'm curious about as a user is whether I only need to have my window open in the browser or also need to have my normal internet connection working.

Ideally, the user would host the content until their friend gets it. Note this is ideally for the IPFS network, I realise it's not the best user-experience.

Of note, due to the way an embedded js-ipfs node works right now, the content will be available for a few hours on the public preload nodes, so in practice they should be able to add the files and go offline, and the recipient could still get them, but in general we have to boost the idea of self hosting, even if it feels less practical right now. We can, and should, point to other services that offer stronger availability guarantees, to support other apps in the ecosystem.

FWIW, I don't think "normal" people know what the word "hypermedia" means,

I Strongly agree. I didn't include it in the new copy proposal for the same reason. Same goes for node. I left it out to reduce the number of new terms.

olizilla commented 5 years ago

@akrych could you give us some design feedback on this. We finally have a proposal for the copy for the share files app!

fsdiogo commented 5 years ago

Current status:

copy
akrych commented 5 years ago

@fsdiogo @olizilla

I personally would reduce a little the icons and stick it to the top. Besides this, everything looks great, good work! :D 👍

share

fsdiogo commented 5 years ago

I added one file in Chrome, copied the link, and opened it in Firefox where I see the download button for that one file. When I added another file, there was nothing noticeable to indicate that the URL had changed and that I'd need to send it to my friend again if I wanted them to have access to both files.

I'd recommend adding some text as soon as any subsequent file is added to note that the folder URL has changed, and also making the links for individual files available by clicking next to them if that's an option.

I agree with that, if you add a file first and then add another, the share link changes without warning the user that it did. I'll think of something to circumvent that.

I also don't see a way to go back and get a URL for just one of files if I only want to share one of them instead of the whole current batch. Is that possible and I'm missing how to do it?

There's no way to do that. If you want to share one file, you just add that one. Why add a bunch of them if you just want to share one in specific? 🤔

As a receiver, my expectation is that I can click on the "Download All" button to download all shared files or click on the individual icons to download a single file. None of the buttons appear to work. The individual buttons flash and the "Download All" button changes to "Downloading" with a gray circle next to it, but there's no pop-up like I'd normally see in my browser and nothing new in my downloads folder while in Firefox. Where should I find the downloaded files? Or do they just download so slowly that I'll give up before receiving them? In Chrome, the individual icons work with my system dialog but the "Download All" button doesn't work in the same way described above.

That isn't supposed to happen, it should work. Earlier @lidel pointed something out that might be related, i.e, if you try to download a file without having connected to a bootstrap node, the UI hangs. When everything is working the download goes to your download folder, as per the browser settings.

fsdiogo commented 5 years ago

I personally would reduce a little the icons and stick it to the top. Besides this, everything looks great, good work! :D 👍

Sounds good @akrych, thanks!

I'll open a WIP PR soon.

terichadbourne commented 5 years ago

@olizilla I was half reading your proposed copy and half playing with the current site, so I missed that you'd removed that tagline, sorry.

I switched it to share link in the copy and the other images. I think that's simpler. I agree if we go with URL it should be capitalised. @terichadbourne do you have a preference for share URL or share link?

I think I would using "sharing link" over "share link" or "share URL." As a verb you would share the link but I wouldn't use share as an adjective to modify link.

Ideally, the user would host the content until their friend gets it. Note this is ideally for the IPFS network, I realise it's not the best user-experience.

Of note, due to the way an embedded js-ipfs node works right now, the content will be available for a few hours on the public preload nodes, so in practice they should be able to add the files and go offline, and the recipient could still get them, but in general we have to boost the idea of self hosting, even if it feels less practical right now. We can, and should, point to other services that offer stronger availability guarantees, to support other apps in the ecosystem.

I'm interpreting this as "Yes, the files are using the normal internet to get transferred, not magically flying through the Ether or Bluetooth or something like that, so the recipient and at least one other person who already has the file need their WiFi turned on." This app feels a lot like an AirDrop equivalent which I'm under the impression doesn't require WiFi, which is why I asked.

@fsdiogo

There's no way to do that. If you want to share one file, you just add that one. Why add a bunch of them if you just want to share one in specific? 🤔

Let's say I just added three files that Oli needs, and I successfully figured out that I needed to share the link after all three were there to give him access to all three (which hopefully I will after we add an explainer). An hour later I realize you need one of those files, but just one. It will annoy me to have to go and upload the same file I already uploaded in order to get it separate from the other two. The interface I'm accustomed to is something like Dropbox where I only have to upload a file once and then I can right click to grab/share a link to a specific file OR a folder of files whenever I want without spending more time uploading again. That limitation means I'll have to invest more work and keep more browser tabs open if I need to keep sharing similar things with a variety of people. This tool feels like it has the usefulness of a one-and-done service like Air Drop, not the long-term utility of a Dropbox, Box, Drive, etc. that's more versatile. If it's a real limitation in what can be accomplished with IPFS, that's fine, but if you could save the CID for that specific document and make it available without too much trouble, it would be a huge UX gain in my opinion.

That isn't supposed to happen, it should work. Earlier @lidel pointed something out that might be related, i.e, if you try to download a file without having connected to a bootstrap node, the UI hangs. When everything is working the download goes to your download folder, as per the browser settings.

I don't know what a bootstrap node is or how I would connect to it. Is that something that needs to be explained on the download page?

lidel commented 5 years ago

Great feedback happening here! I extracted two actionable issues, so we don't forget about addressing them:

olizilla commented 5 years ago

Thanks @terichadbourne! Yes, I skipped ahead, yes the files are transferred via IP addresses on the regular internet, not bluetooth. IPFS would like to support all the transport layer options so one day it may do both!

This tool feels like it has the usefulness of a one-and-done service like Air Drop, not the long-term utility of a Dropbox, Box, Drive, etc. that's more versatile. If it's a real limitation in what can be accomplished with IPFS, that's fine, but if you could save the CID for that specific document and make it available without too much trouble, it would be a huge UX gain in my opinion.

We can add support for grabbing sharing links for individual items, but we'll focus on robustness of the current feature set first as it sounds like there are some issues there.

More generally, Web UI and IPFS Desktop are the place for a more feature-rich experience. One route to this share app is via Web UI where you may have uploaded all your files already, then you select a batch of them and hit "Share". We made this as a standalone app so that it could be used from Web UI or directly, for quick demos and more simple usecases.

olizilla commented 5 years ago

@fsdiogo i sense that you're not a fan of replacing the "InterPlanatary..." header with "Share files directly from your device". I proposed the new copy to shift the focus to from the tech, to what it enables. I'd like to add a section below the app that gives a high level intro to IPFS and links out to more info. As @terichadbourne pointed out, the strapline

A peer-to-peer hypermedia protocol to make the web faster, safer, and more open.

causes confusion, as most folks wont know what "a hypermedia protocol" is. My sense of this is that we should lead with a headline that clearly describes the value of this particular app "Share files..." and then once people are on-board with the value, then give a more pratical intro to IPFS below the app if they are interested.

fsdiogo commented 5 years ago

@fsdiogo i sense that you're not a fan of replacing the "InterPlanatary..." header with "Share files directly from your device".

😄 yeah, at first I wasn't a fan so I didn't change it, but then I gave it a second thought and agreed with you both! It's already changed in the PR 🙂

olizilla commented 5 years ago

@fsdiogo 💞 I should also say that I very much like the improvements to the icons, colors, and layout that you've found. The contrast between the bullet points and the headers works really well, and lining the text up with the bar in the header looks sharp. 👨‍🍳👌 bellisimo

fsdiogo commented 5 years ago

Thanks, I did some experiments and this was the look I liked best 😄

and lining the text up with the bar in the header looks sharp.

I can't take credit for that as it was a coincidence in the screenshot 😂

fsdiogo commented 5 years ago

Add page copy

add

Download page copy

download
fsdiogo commented 5 years ago

What about changing the left side of the footer to something that links to the GitHub repo? As we already have the PL logo on the right side, I don't think it's worth repeating it on the left side.

olizilla commented 5 years ago

Hmm. Now I see it, I'm thinking that we could keep the copy on the left the same and add a header to the files box that says something like "These 5 files are being shared with you via IPFS. Download them then leave this page open to help co-host them"

fsdiogo commented 5 years ago

That could work, but as the copy is more of a 'how to use the app', in the download page it should follow the same principle, although the copy is similar.

terichadbourne commented 5 years ago

I agree with @fsdiogo that because you're now using steps to take, rather than features, as the list on the left, it would be confusing to leave those sharing steps on the download page. I'm not opposed to minimalist copy that doesn't mirror the format of the other page, just opposed to repeating the content.

If you do decide to leave detailed steps like those proposed in the screenshot, I'd avoid using the word "archive," which to normal people means old historical stuff, not a folder (or folder of folders) of current stuff.

fsdiogo commented 5 years ago

@terichadbourne I'm using archive because you really get a *.tar.gz when downloading all files, but I get your point. Do you have a suggestion for a better word?

terichadbourne commented 5 years ago

@fsdiogo I've never in my life seen that file extension, but I just tried another share to see how it saved and it calls itself a "GZip archive" in a Mac save box. Do all unzipper applications know how to deal with this particular file extension? If so, I'd call it a "zip file" so people who know how to open those will follow the steps they're accustomed to. In this case, your blurb could change to "You can download all shared files and folders as a zip file, or select an individual file or folder to download."

Note that I was surprised to see folders in your sample because on the upload screen it says to add a file and it never occurred to me that I could upload a folder instead.

fsdiogo commented 5 years ago

Do all unzipper applications know how to deal with this particular file extension? If so, I'd call it a "zip file" so people who know how to open those will follow the steps they're accustomed to."

The popular unzipper apps will know how to deal with .tar.gz. Calling it a zip a file doesn't seem correct, as there are differences between zip and tar files.

Note that I was surprised to see folders in your sample because on the upload screen it says to add a file and it never occurred to me that I could upload a folder instead.

Well, you can't upload folders, so that's why the copy focus on files. In my screenshot you can see folders, but you can only achieve that when sharing from the Web UI. It then lets you download files/folders/all.

terichadbourne commented 5 years ago

The popular unzipper apps will know how to deal with .tar.gz. Calling it a zip a file doesn't seem correct, as there are differences between zip and tar files.

From my perhaps naive perspective, don't think any of the distinctions between tar and zip files in that SO issue matter to the end user of the sharing app, who at most needs to know that they'll need to use an unzipper on the thing that gets downloaded. But if you're not comfortable using the phrase zip file I think you're better off ignoring the issue altogether, because no one knows what an archive file is and they'll likely see a zipper icon on the thing they download and attempt to use their unzipper app to open it without more direction from us.

fsdiogo commented 5 years ago

@terichadbourne what about bundle? I think that works.

terichadbourne commented 5 years ago

My gut reaction is that although "bundle" doesn't have the stale historical connotation of archive, it doesn't mean anything to a normal user in this context. "Download all" already carries a set of expectations that are met by ending up with a zip-looking file on your laptop, so I'd skip the explanation of in what file format the "download all" will deliver the files. Unless of course you want to call it a folder because that's what it will unzip/unarchive to, but no specific need to do that.