Add a notes section for developers and users to comment/note workflow and script usage/instructions/features...

[twinpeaks]

Preface:  Please bear with me on this one, I was a bit excited writing about this feature request so I am sure I repeat myself plenty but a quick read and the screenshot should tell it all. Thank you!

 

The workflow section is amazing and with the new layout of workflows I think it would be even better if workflow creators could give users notes about usage and possible variables that need to be adjusted or can be adjusted in various scripts located throughout the workflow.

 

Yes, I know titles and subtext exist to explain the basic idea behind what a workflow does, but as of now if different parameters can be set within a script the developer either comments the parameters in the script itself, which is always good practice or in the worst case scenario no comments exist and the user searches through the code to figure out what the parameters can be used by double clicking the script icon in the workflow to view the script and/or search for comments containing information about different parameters that the script can take advantage of.

 

I hope this will clear up what I am getting at:

 

Take for example one of Pedro Lobo's wonderful workflows: "Spotlight Comments" - Pedro always comments his code very neatly for users to view parameters and makes a detailed installation and usage instructions for his users wherever he posts the workflow. When a repository is up and running and these wonderful detailed instructions are not joined with the actual workflow download the user is missing a lot.

 

This is what Pedro posted with his workflow:

-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

"Installation and Setup

 

Download and import. As for setup, there isn’t much to it. Simply define what your desired default action should be when encountering existing comments. Change property defaultOverwrite : "append"  accordingly. Possible options are append, replace and interactive.

 

Extension Usage

 

Triggering the extension and entering text without any of the following parameters will default the the behaviour discussed above, with the exception of delete of course.

• -d — Will remove any spotlight comment from the selected files;
• -a — Will append to existing comments;
• -r — Will replace existing comments;
• -i — Will function interactively allowing you to decide on a file by file basis. It will display the existing comment to facilitate your decision too 

There is no need to leave any space after the parameter but you can do so if you prefer (it will be stripped from the begging) 

-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

 

Sometimes after you download a workflow you forget all of this wonderful information.

 

Solution: 

 

 

 

 

 

In the workflow "environment" allow for the developer and users the option of inserting a text field that spanned the bottom of the workflow screen that can be added by the workflow creator and especially the user to make comments about the workflow.

 

1) It could be used for jotting ideas while creating workflows.

2) Wouldn't require remembering where a workflow was downloaded from and visiting that site (if a site is listed in details) to learn more about it.

3) Usage instructions would be right their for you to see at a glance.

4) When making modifications to someone else's workflow, note your changes.

 

So many great uses for a feature like this and I beg of you, If you implement any feature I ask for during this beta period, PLEASE let it be this one!!

 

Keep interface clean:

The text Field could slide up from the bottom if added and then collapsed again to make the workflow view clean and pretty but when you need the details or want to make a quick note, you can pull it up and edit away never again forgetting important info about the workflow.

 

I am sure Andrew will have a great way to implement this. Please vote it up so it happens, thank you to everyone for sharing their workflows and again to the Alfred team for letting me beta test and make feature requests. Cheers!

[palobo]

Yeah, I can totally agree that this would be a killer addition. To reduce visual clutter a simple "i" button near the top could open a new sheet with this information. Also great for changelog etc.

 

Ignore the crappy example of course

[jdfwarrior]

Pedro may be on to something I like that idea.

 

As for a large box at the bottom, that removes too much space for your workflow. When you begin creating large workflow with multiple commands, actions, outputs, etc it can get very cluttered. AlfredTweet is large hehe

[twinpeaks]

Yeah, for sure. That is why I mentioned maybe that the box could slide down to clear clutter but I like Pedro's implementation even better as it would be easier to access and view while not disturbing huge workflows either. I just really want a sheet of some kind where usage information, changes, general ideas for the workflow can be easily accessed from within each workflow's "section."

 

I am glad my two favorite workflow creators think this is a good idea! Your support and extensions are much appreciated boys. Ah, so glad to see you two posted here so thanks for that and everything else you do!

 

If anybody has the pull to get a feature implemented it's David…  

 

Cheers!

[CarlosNZ]

This is a good idea, and perhaps you could include a couple of user-input text fields where the user can enter values needed for the script to run, eg. an API key, or in Pedro's case "overwrite, append or replace". Though that should really be a selector of some sort.

[jdfwarrior]

This is a good idea, and perhaps you could include a couple of user-input text fields where the user can enter values needed for the script to run, eg. an API key, or in Pedro's case "overwrite, append or replace". Though that should really be a selector of some sort.

 

I've suggested something similar before too since i've had several extensions and such that require username and password or something kind of api key. Hopefully this kind of thing can be implemented one day.

[jdfwarrior]

Yeah, for sure. That is why I mentioned maybe that the box could slide down to clear clutter but I like Pedro's implementation even better as it would be easier to access and view while not disturbing huge workflows either. I just really want a sheet of some kind where usage information, changes, general ideas for the workflow can be easily accessed from within each workflow's "section."

 

I am glad my two favorite workflow creators think this is a good idea! Your support and extensions are much appreciated boys. Ah, so glad to see you two posted here so thanks for that and everything else you do!

 

If anybody has the pull to get a feature implemented it's David…  

 

Cheers!

 

Yeah sorry, if it slides up from a hidden area to work with and then goes away, that would be nice. Honestly, I looked at your post, skipped to the picture and kept going It was a little too long for my ADD at the moment

[twinpeaks]

Haha, you've got add and I have ocd. It's all good. I am sure Andrew will figure out a good way to implement this if it does indeed get picked up. Still keeping my fingers crossed… 

[tomhunt]

+1 for this please

[CarlosNZ]

I've suggested something similar before too since i've had several extensions and such that require username and password or something kind of api key. Hopefully this kind of thing can be implemented one day.

Thinking about this some more, I'd actually consider it fairly important from a security point of view. With all the exuberant sharing of new workflows going on round here, it's surely only a matter of time before someone exports their workflow and forgets to remove their own personal ID information first. We could really do with some "protected" fields which are not exported with the rest of the workflows.

[jdfwarrior]

Thinking about this some more, I'd actually consider it fairly important from a security point of view. With all the exuberant sharing of new workflows going on round here, it's surely only a matter of time before someone exports their workflow and forgets to remove their own personal ID information first. We could really do with some "protected" fields which are not exported with the rest of the workflows.

 

If you check the recommended best practices post I made the other day you will see that it is suggested that you don't store data in the workflow folder anyway. That being said, if you follow those guidelines and store data in the way recommended in that post, this won't be an issue.

[CarlosNZ]

If you check the recommended best practices post I made the other day you will see that it is suggested that you don't store data in the workflow folder anyway. That being said, if you follow those guidelines and store data in the way recommended in that post, this won't be an issue.

This is true, but that makes it a lot trickier to write a simple workflow that requires personal data. Most of the workflows shared around here so far have just asked the user to enter their info in the script window, with some commented info explaining what to do. If we're going to put user info into the appropriate working folders (which, obviously, we should), then workflows that require this will have to write some kind of "input" routine into their workflow. Maybe it could be "keyword user 'myusername'" in Alfred or something, or, even better, a GUI that pops up on first run and asks for the relevant details. This would be really nice, but it's obviously quite a bit of extra work. I guess the thing to do would be for someone (any volunteers? myself perhaps?) to write a boilerplate AppleScript GUI that other workflow developers can reuse, that can be inserted at the start of the workflow and executed on first run. If you think something like this is a good idea, then maybe I'll start a thread to discuss it and get come collaborative input from others to get the ball rolling. Or has anyone got another obvious idea for how to handle user data that a) is not too much work, or can be generalised to be re-used by other developers?

 

Sorry for the rambling post, just thinking "out loud", so to speak.

[BrianGilbert_]

This is true, but that makes it a lot trickier to write a simple workflow that requires personal data. Most of the workflows shared around here so far have just asked the user to enter their info in the script window, with some commented info explaining what to do. If we're going to put user info into the appropriate working folders (which, obviously, we should), then workflows that require this will have to write some kind of "input" routine into their workflow. Maybe it could be "keyword user 'myusername'" in Alfred or something, or, even better, a GUI that pops up on first run and asks for the relevant details. This would be really nice, but it's obviously quite a bit of extra work. I guess the thing to do would be for someone (any volunteers? myself perhaps?) to write a boilerplate AppleScript GUI that other workflow developers can reuse, that can be inserted at the start of the workflow and executed on first run. If you think something like this is a good idea, then maybe I'll start a thread to discuss it and get come collaborative input from others to get the ball rolling. Or has anyone got another obvious idea for how to handle user data that a) is not too much work, or can be generalised to be re-used by other developers?

 

Sorry for the rambling post, just thinking "out loud", so to speak.

I don't see why you couldn't store the information in some form of file that contains the information at the suggested paths and have your workflow load it from there to populate the variables where they need to be, I'm doing that for a workflow that I'm currently working on.

 

edit: ah.. on fully reading your comment I see the problem is getting the input to start with..

[CarlosNZ]

I don't see why you couldn't store the information in some form of file that contains the information at the suggested paths and have your workflow load it from there to populate the variables where they need to be, I'm doing that for a workflow that I'm currently working on.

 

edit: ah.. on fully reading your comment I see the problem is getting the input to start with..

Ah yes indeed. I see you've edited your post between when I first read it to when I was about to reply. Good we're on the same page now.

[palobo]

For me, an ideal way of dealing with this would be to have an extra "action block" in the workflow. Imagine a block you can drag onto the workflow canvas and add any number of key:value pairs that would then be fed into the other blocks.

Of course Andrew would have to weigh in on this with regards to complexity of such an implementation. Otherwise, it shouldn't be too hard to write, as CarlosNZ suggested, an AppleScript boilerplate for requesting some initial user input and saving this in a pliant,Jason, Xmas file in the workflow non-volatile directory.

[CarlosNZ]

For me, an ideal way of dealing with this would be to have an extra "action block" in the workflow. Imagine a block you can drag onto the workflow canvas and add any number of key:value pairs that would then be fed into the other blocks. Of course Andrew would have to weigh in on this with regards to complexity of such an implementation.

Yeah, I wonder if Andrew might, when he's got a spare minute , let us know what, if anything, his plans might be in this area. If there's going to be "user input" box in workflow configs at some point, then it would make sense just to make do until such time as that becomes available. But if not, then I think it would be a good idea to get a discussion going as to the best way to standardise the (non-trivial) issue of acquiring user-specific data.

 

FWIW, the reason I'm thinking about this is that I was about to try and update one of my workflows so that the user could specify the storage location for their stored strings, and therefore sync it to their Dropbox if they want. However, the workflow is a pretty basic one, and implementing this feature would more than double the amount of code if I was to do it in an elegant and fool-proof way. Not that I'm against such a thing, it's still not exactly a huge deal, but if would be great if the process for acquiring user data was standardized somewhat so we could all share the code. (Off the top of my head, I'm thinking .plist files for settings, and a php-driven web interface for users to edit their settings across all compliant workflows.)

[twinpeaks]

No "action block" ... yet but we now do have a "readme" tab! Double click the workflow (where you would edit the bundle id, workflow name, creator, etc..) and to the right is a tab labeled readme to put in some info/uses/variables about the workflow. Nothing more than a simple area for info but it's good enough for me.

 

You developers will need to push harder for your "action block" idea, which is great imo, so keep at it, I am sure it will eventually make it into Alfred.

 

Thanks Alfred team for implementing my request.  knew you two would think of a cleaner way of doing it than a sliding notepad from the bottom of the workflow as I suggested. Cheers!  

[renegaed]

It would be great if this feature were implemented similar to github which parses a README.md file and provides support or Markdown. The documentation could be more verbose and better organised.

 

Also I like the idea of an "info" button which calls a slider from the bottom over the current implementation of a readme tab. IMO it's much more appealing to want to take action on.

[deanishe]

The current README tab is not very good, particularly but not only because it only supports plain text.

Any system that Alfred used to show help/docs should, in my opinion and unlike the current README tab, make it possible to view the documentation alongside Alfred/Alfred Preferences, so I can read it while working on/with the workflow.

Having the help info in a modal sheet that blocks your view of and access to the thing its about is sub-optimal.

As plaintext in a modal sheet, the README tab is fine for an "About this Workflow" dialog, but not a great place for help/docs.

I like renegaed's Markdown idea, but Markdown is not everybody's cup of tea. Rich text might be a safer bet.

Regarding workflow setting, I'd definitely like Alfred to gain some features in that direction. I've already put in the hard work of providing access to data & cache directories and Keychain to workflows via Alfred-Workflow, but I still have to code the settings interface for every workflow, and it's often at least as much effort to write as the actual functionality of the workflow.

I'd also like to see a third user data directory (alongside the data and cache ones) for sync data that would live in the synced Alfred.alfredpreferences bundle. It would be at ../../Workflow Sync/your.bundle.id.here relative to the workflow's root.

Edited May 11, 2015 by deanishe