Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation for deleting files (improvement) #791

Merged
merged 9 commits into from
Dec 7, 2020
Merged

Documentation for deleting files (improvement) #791

Changes from 8 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
d61b9db
Merge commit 'e129790ed587819ecfcaed59fc7ff90ec6ffcfa1' into gh-pages
mtrezza Sep 6, 2019
9cc311c
Merge remote-tracking branch 'upstream/gh-pages' into gh-pages
mtrezza Nov 15, 2019
d425b11
Merge commit 'cc489df4a3d8544a52148c079ecaee3d1762108d' into gh-pages
mtrezza Jan 9, 2020
ddb5cb1
Merge remote-tracking branch 'upstream/gh-pages' into gh-pages
mtrezza Apr 18, 2020
3cf6398
Merge remote-tracking branch 'upstream/gh-pages' into gh-pages
mtrezza Jul 11, 2020
5e6c8fa
Merge remote-tracking branch 'upstream/gh-pages' into gh-pages
mtrezza Nov 17, 2020
b62ab67
improved JS doc for deleting file
mtrezza Nov 17, 2020
6a63e8d
removed required reference to delete file
mtrezza Nov 18, 2020
c320d7e
changed bullet point to headline
mtrezza Nov 27, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 7 additions & 10 deletions _includes/js/files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,20 +113,17 @@ Parse.Cloud.httpRequest({ url: profilePhoto.url() }).then(function(response) {

## Deleting Files

You can delete files that are referenced by objects using the [REST API]({{ site.baseUrl }}/rest/guide/#deleting-files). You will need to provide the master key in order to be allowed to delete a file.

If your files are not referenced by any object in your app, it is not possible to delete them through the REST API.

Alternatively, starting with Parse Server 4.2.0, you can delete files using cloud code.
You can delete files that are referenced by objects using the `destroy` method. The master key is required to delete a file.

```javascript
Parse.Cloud.beforeDelete('Profile', async (req) => {
const profile = req.object;
const profilePhoto = profile.get("photoFile");
await profilePhoto.destroy({ useMasterKey: true })
});
const profilePhoto = profile.get("photoFile");
await profilePhoto.destroy({ useMasterKey: true });
```

* Parse Server <4.2.0

The `destroy` method is available since Parse Server 4.2.0, for lower versions use the [REST API]({{ site.baseUrl }}/rest/guide/#deleting-files) to delete a file.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's unnecessary to mention the 4.2.0 requirement twice here. I suggest removing the bullet point. Perhaps it would be nice have a note below the Deleting Files title. Something like this... Available only on Parse Server Cloud Code starting 4.2.0

Copy link
Member Author

@mtrezza mtrezza Nov 19, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's unnecessary to mention the 4.2.0 requirement twice here.

Yea, that seems redundant. How about:

  • Parse Server <4.2.0
    The destroy method is available since Parse Server 4.2.0, for lower versions Use the REST API to delete a file.

I suggest removing the bullet point.

My thinking was that the docs should always reflect the newest version. Any notes regarding previous versions are becoming negligible and should therefore be below, marked with their own headline or bullet point, ordered by relevance descending. The layout would be:

< DOC FOR NEWEST VERSION, high relevance >

  • Parse Server <4.2.0
    < DOC FOR VERSION <4.2, medium relevance >

  • Parse Server <2.2.0
    < DOC FOR VERSION <2.2, low relevance >

What do you think?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Parse Server <4.2.0
    The destroy method is available since Parse Server 4.2.0, for lower versions Use the REST API to delete a file.

Wording wise that works

My thinking was that the docs should always reflect the newest version. Any notes regarding previous versions are becoming negligible and should therefore be below, marked with their own headline or bullet point, ordered by relevance descending. The layout would be:

< DOC FOR NEWEST VERSION, high relevance >

  • Parse Server <4.2.0
    < DOC FOR VERSION <4.2, medium relevance >
  • Parse Server <2.2.0
    < DOC FOR VERSION <2.2, low relevance >

What do you think?

Ahh, I didn't realise you were using the bullet point as a form of heading. I agree with the hierarchy.

I don't think the layout for the older versions works as the line(s) below aren't indented. I would suggest either having the whole doc on the bullet point or using an actual heading like ###.

Could you also add Available only on Parse Server Cloud Code starting 4.2.0 under neither the main Deleting Files heading?

Copy link
Member Author

@mtrezza mtrezza Nov 27, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think the layout for the older versions works as the line(s) below aren't indented. I would suggest either having the whole doc on the bullet point or using an actual heading like ###.

Right, that makes sense, I'll change that.

Could you also add Available only on Parse Server Cloud Code starting 4.2.0 under neither the main Deleting Files heading?

When I look into the docs, I often stumble upon a "Available since parse server 2.x", and it never fails to irritate me. I think visual real estate should ideally contain only info that is useful, but these notes are not useful for maybe 99% of readers, because they use a version >2.x. Basically, these notes become pretty old pretty fast.

So instead of saying:

Amazing feature

Available since Parse Server 4.2.

Do this...

I would say:

Amazing feature

Do this...

Parse Server <4.2

This feature is not available.

because it would be consistent with this schema:

Amazing feature

Do this...

Parse Server <4.2

Do that instead...

Parse Server <4.0

Do something else instead...

This way the notes are used has headlines and denote their own doc block without interfering with the section that documents the status quo.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find this contradictory, you are saying that a 1 line note at the top irritates you and is not useful but also suggesting documenting potentially multiple older versions below?

Notes about features available on 2.x should probably be removed but personally I like the notes about recent releases at the top as it hopefully helps to prevent people wasting time trying to use features which don't exist on their version and helps to showcase the improvements being made across the platform.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we think the same :)

What I mean is that a line at the top "available since..." is unnecessary for most readers and therefore should be avoided because it is placed before the information the reader is actually looking for.

A line at the bottom "on lower version use workaround..." is not as disturbing since it is placed below the information most readers are looking for.

Now, whether it should be mentioned that a feature is not available or that there is a workaround for lower versions is a different question. I think it should, and there may be better forms of denoting the availability of features.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry for the lack of reply!

I'm not sure I agree with your assumptions about 'most readers' but I really don't have the head space to discuss this further at the moment.

I'll merge the PR as it's definitely as improvement regardless!

## Adding Metadata and Tags

Adding Metadata and Tags to your files allows you to add additional bits of data to the files that are stored within your storage solution (i.e AWS S3).
Expand Down