Documentation for deleting files (improvement)

[mtrezza]

Improving on #789:

• Clarified wording; it could be understood that for Parse Server <4.2.0 it is not possible to delete a file using Cloud Code, which is incorrect.
• Simplified example code; it is not necessary to use a beforeDelete hook the example; given the beforeDelete name, one could assume that it is somehow related to the basic functionality of deleting a file, which it is not.

[mtrezza]

[redacted]

[TomWFox]

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

[mtrezza]

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?

[TomWFox]

• 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?

[mtrezza]

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.

[TomWFox]

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.

[mtrezza]

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.

[TomWFox]

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!