[DX] Documentation Tweaks #273

Closed
weaverryan opened this Issue Jul 5, 2014 · 10 comments

Comments

Projects
None yet
3 participants
@weaverryan

Hi guys!

I do really like this bundle, but wanted to suggest some documentation improvements aimed at making sure beginners don't have issues. There are probably more things that can be done, but here are some quick ones:

Thanks!

agallou added a commit to agallou/VichUploaderBundle that referenced this issue Jul 5, 2014

move flysystem and gaufrette configuration to its own pages
Moving this makes the "Annotate Entites" more visible.

See #273

agallou added a commit to agallou/VichUploaderBundle that referenced this issue Jul 5, 2014

agallou added a commit to agallou/VichUploaderBundle that referenced this issue Jul 5, 2014

@agallou

This comment has been minimized.

Show comment
Hide comment
@agallou

agallou Jul 5, 2014

Contributor

@weaverryan for the last point, adding a link to the known issues just after the example of the "Annotate Entities" in the "usage" page could do the trick ?

Contributor

agallou commented Jul 5, 2014

@weaverryan for the last point, adding a link to the known issues just after the example of the "Annotate Entities" in the "usage" page could do the trick ?

@agallou

This comment has been minimized.

Show comment
Hide comment
@agallou

agallou Jul 14, 2014

Contributor
Contributor

agallou commented Jul 14, 2014

@weaverryan

This comment has been minimized.

Show comment
Hide comment
@weaverryan

weaverryan Jul 15, 2014

@agallou, yea awesome! I've converted my points to checkboxes and checked off the first and third.

About the last point (F), the solution you're proposing would certainly be better than now. But, I also wonder why we don't just recommend that people set their "filename" (e.g. imageName) property to null to trigger the dirty entity. After all, at the moment the file property (e.g. image) is set, the imageName is technically wrong until everything is persisted.

Thanks!

@agallou, yea awesome! I've converted my points to checkboxes and checked off the first and third.

About the last point (F), the solution you're proposing would certainly be better than now. But, I also wonder why we don't just recommend that people set their "filename" (e.g. imageName) property to null to trigger the dirty entity. After all, at the moment the file property (e.g. image) is set, the imageName is technically wrong until everything is persisted.

Thanks!

@agallou

This comment has been minimized.

Show comment
Hide comment
@agallou

agallou Jul 15, 2014

Contributor

@weaverryan the D and E points has also been done (in PRs #274 and #275)

Contributor

agallou commented Jul 15, 2014

@weaverryan the D and E points has also been done (in PRs #274 and #275)

@weaverryan

This comment has been minimized.

Show comment
Hide comment
@weaverryan

weaverryan Jul 15, 2014

@agallou you're awesome :). We're almost there! We could potentially propose the (F) change (setting imageName to null in setImage) and see what people say when they actually see the code change. We basically need some additional people to weigh on and see if there are any disadvantages/risks to this approach.

@agallou you're awesome :). We're almost there! We could potentially propose the (F) change (setting imageName to null in setImage) and see what people say when they actually see the code change. We basically need some additional people to weigh on and see if there are any disadvantages/risks to this approach.

@K-Phoen

This comment has been minimized.

Show comment
Hide comment
@K-Phoen

K-Phoen Jul 15, 2014

Collaborator

@weaverryan you are absolutely right: we should advise our users to set set their "filename" to null.

I wanted to go further with the documentation refactoring and created a PR in which I try to make it simpler to follow for new users. It's still WIP but any thoughts on what I did? (writing documentation - moreover in english - isn't really my strongest point).

Collaborator

K-Phoen commented Jul 15, 2014

@weaverryan you are absolutely right: we should advise our users to set set their "filename" to null.

I wanted to go further with the documentation refactoring and created a PR in which I try to make it simpler to follow for new users. It's still WIP but any thoughts on what I did? (writing documentation - moreover in english - isn't really my strongest point).

@weaverryan

This comment has been minimized.

Show comment
Hide comment
@weaverryan

weaverryan Jul 15, 2014

@K-Phoen It's awesome man! I just left you a ton of comments. This is exactly what I was hoping for! My goal is to link to this bundle from the official docs when we're all happy.

Thanks!

@K-Phoen It's awesome man! I just left you a ton of comments. This is exactly what I was hoping for! My goal is to link to this bundle from the official docs when we're all happy.

Thanks!

@K-Phoen

This comment has been minimized.

Show comment
Hide comment
@K-Phoen

K-Phoen Jul 15, 2014

Collaborator

Wow, you really are awesome! Thanks for all your great advice! 👍

I modified the documentation accordingly :)

Collaborator

K-Phoen commented Jul 15, 2014

Wow, you really are awesome! Thanks for all your great advice! 👍

I modified the documentation accordingly :)

@K-Phoen

This comment has been minimized.

Show comment
Hide comment
@K-Phoen

K-Phoen Jul 21, 2014

Collaborator

With the PR #281 merged, this issue is solved :)

Collaborator

K-Phoen commented Jul 21, 2014

With the PR #281 merged, this issue is solved :)

@K-Phoen K-Phoen closed this Jul 21, 2014

@weaverryan

This comment has been minimized.

Show comment
Hide comment
@weaverryan

weaverryan Jul 22, 2014

Great job guys! This is a stand-out example of wonderful bundle documentation.

Thanks!

Great job guys! This is a stand-out example of wonderful bundle documentation.

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment