Overhaul documentation on structuring software

[WardLT]

Description

Makes changes that we discussed during a community call back in May:

• Emphasize keeping decorators out of the main library
• Discuss benefits of modules for serializing functions
• Propose defining separate "workflow-ready" functions in module
• General clean up of dicsussion

cc: @Andrew-S-Rosen

Changed Behaviour

N/A

Fixes

None

Type of change

• Update to human readable text: Documentation/error messages/comments

[Andrew-S-Rosen]

@WardLT: This is great! Thank you for putting this together. I think this is a big improvement.

[One practical challenge with this approach that I'll note from experience is that if the code maintainer is running tests without Parsl at all, they may run into problems when using Parsl if there are complex workflow patterns (think @join_app, for instance). In other words, things might run fine without Parsl but crash with Parsl. This is especially likely if you have contributors who are pushing "pure Python" code and know nothing about Parsl so aren't thinking about designing the codebase with Parsl in mind. I usually recommend having a separate Parsl-enabled test suite for this purpose, but I think this is a bit much for the docs.]

[WardLT]

Thanks, Andrew! I'll see if I can work in a short mention of tests for join apps and such

[benclifford]

@WardLT want to merge that doc change now and then submit another one with more work, or work on it more before merging?

[WardLT]

I'm happy with what I have here and am fine with merging it in. I might touch this part later, but plan to work on some other parts of the docs next