Jump to content
terryzx

Any Chance of Getting a User Manual

Recommended Posts

Any chance there is or will be an actual user manual? There are so many things that can be done, I would like to have a list and explanation of how to use them all. This would make the program much more user friendly for people who might not be aware of it all....?

Share this post


Link to post

Any chance there is or will be an actual user manual? There are so many things that can be done, I would like to have a list and explanation of how to use them all. This would make the program much more user friendly for people who might not be aware of it all....?

 

Covering everything in a user manual would be extremely complicated because, as you mentioned, there are so many things that can be done. Is there something in particular that you'd wish to learn about or something you'd like explained a little more? We'd be more than happy to help out in any way possible.

Share this post


Link to post

Covering everything in a user manual would be extremely complicated because, as you mentioned, there are so many things that can be done. Is there something in particular that you'd wish to learn about or something you'd like explained a little more? We'd be more than happy to help out in any way possible.

Nothing in particular but I was just wondering what I might be missing that could be done that I might be doing with other apps currently.

Share this post


Link to post

Covering everything in a user manual would be extremely complicated because, as you mentioned, there are so many things that can be done. Is there something in particular that you'd wish to learn about or something you'd like explained a little more? We'd be more than happy to help out in any way possible.

 

And that's exactly the reason there should be some kind of manual.

 

It was over a year before I learnt that Alfred has a history of your searches, which is a pretty important feature, imo.

 

Similarly, there's no proper documentation for workflow authors. What there is is spread across many forum threads. Instead of there being one definitive, informative and up-to-date source, you have to trawl through pages of posts in forum threads trying to work out what has changed since the original post.

 

For example, the fact that arg can also be a tag instead of an attribute is 4 pages and 80 posts into the thread on feedback.

 

The thread on libraries and helpers is also full of stuff that's essentially been discontinued or abandoned.

 

This forum is a great resource for users and developers, but it is not a good replacement for a proper user manual, a developer reference or a directory of workflows.

Share this post


Link to post

And that's exactly the reason there should be some kind of manual.

 

It was over a year before I learnt that Alfred has a history of your searches, which is a pretty important feature, imo.

 

Similarly, there's no proper documentation for workflow authors. What there is is spread across many forum threads. Instead of there being one definitive, informative and up-to-date source, you have to trawl through pages of posts in forum threads trying to work out what has changed since the original post.

 

For example, the fact that arg can also be a tag instead of an attribute is 4 pages and 80 posts into the thread on feedback.

 

The thread on libraries and helpers is also full of stuff that's essentially been discontinued or abandoned.

 

This forum is a great resource for users and developers, but it is not a good replacement for a proper user manual, a developer reference or a directory of workflows.

 

The fact that it would be nearly impossible to document everything that COULD be done with Alfred because that's only limited to the user's imagination is exactly why there should be a manual? Perhaps there could be a manual for some of the basic things but everything that could ever possibly be done with Alfred can't be covered in a manual.

 

I'll agree that the feedback thread probably does need to be touched and updated a little but it covers 90% of the feedback that Alfred uses. Saying that you have to trawl through pages of posts and threads is a bit of a stretch.

 

The libraries and helpers thread is not discontinued and abandoned. The second paragraph says:

"If you have another utility class that needs to be included in this list, send me a message or email (david@alfredapp.com) with information about it (name, description, short list of features, link to post or download page) and I will make sure that it gets added to the list."

Every library and utility that has been sent to me is in that list. If there is something that isn't on there, it's because the developer hasn't requested for it to be added to the list.

 

Also, the feedback system should always stay in a web based form so there aren't multiple, outdated versions floating around. There should be a single source that stays up to date. I'll see if I can get a few things updated on it soon.

Share this post


Link to post

The fact that it would be nearly impossible to document everything that COULD be done with Alfred because that's only limited to the user's imagination is exactly why there should be a manual? Perhaps there could be a manual for some of the basic things but everything that could ever possibly be done with Alfred can't be covered in a manual.

You're conflating what can be done with how to do it.

Alfred's use cases may be practically infinite, but its interface is both defined and finite. And it should be documented.

 

Alfred's interface is pretty elegant, but it's also somewhat non-obvious, and a "handbook" a few pages long would cover all the essentials admirably.

 

Explain what SHIFT and the arrow keys do, explain about TAB and modifiers keys, file system browsing and adding multiple files to the stack to action them.

 

I'll agree that the feedback thread probably does need to be touched and updated a little but it covers 90% of the feedback that Alfred uses. Saying that you have to trawl through pages of posts and threads is a bit of a stretch.

Okay. Then where is the explanation of how to set custom modifier subtexts in results? It isn't in that thread… :(

 

The libraries and helpers thread is not discontinued and abandoned. The second paragraph says:

"If you have another utility class that needs to be included in this list, send me a message or email (david@alfredapp.com) with information about it (name, description, short list of features, link to post or download page) and I will make sure that it gets added to the list."
Every library and utility that has been sent to me is in that list. If there is something that isn't on there, it's because the developer hasn't requested for it to be added to the list.

 

I didn't say the thread was discontinued or abandoned, I said that a lot of the libraries/utilities in it have been discontinued/abandoned.

Phyllisstein has explicitly stated that Alleyoop is abandonware.

None of the libraries are actually broken AFAIK, but neither have any been updated in ~1 year apart from mine (and perhaps yours—there's no obvious way to tell), so they don't support arg as a tag or custom subtexts :(

 

You've sticked and locked the thread, so it's impossible for anyone else to point out if one of the libraries no longer "Supports all Alfred 2 workflow features" (Alfredo) or when an author has explicitly abandoned the listed project, as with Alleyoop (and, I believe, Alp). That kinda puts the onus on you to keep it up to date.

 

Also, the feedback system should always stay in a web based form so there aren't multiple, outdated versions floating around. There should be a single source that stays up to date. I'll see if I can get a few things updated on it soon.

Exactly. Like I said: "one definitive, informative and up-to-date source". If stickied threads are the chosen form of documentation, so be it, but please keep them up to date by adding any relevant new information to the OP.

Edited by deanishe

Share this post


Link to post

Why not make a list of all the things that Alfred can do and then post the list and make the list all hyperlinks that would go to discussions or directions of how to do these things. That would at least be a good place to start off for people who might not be aware of ALL the available and newly found functions.

Share this post


Link to post

As David says, you can't reasonably create a list of all the things Alfred can do (it's too flexible), but there can and should be a manual describing how to do them (the interface is elegant, and tightly defined, but non-obvious).

 

I'd argue for the creation of a wiki for Alfred documentation.

 

This forum is a great Q&A resource for users and developers, but as noted above, it is far from ideal as a source of documentation or as a directory of workflows. Shawn's Packal has already solved the second problem,  but the documentation for users and developers is a mess.

 

As you note, there is no user manual (and it needn't be a big document—what Alfred can do is unrestricted, but how it does it is clearly defined, and that's the important information).

 

Perhaps more importantly (this information is far more subject to change, and workflows are where much of Alfred's value comes from), there is no decent documentation available for developers. What little there is, is fragmented and often out of date.

 

As most developers will tell you, one of the things most likely to send you running off looking for an alternative library/platform is bad documentation.

 

While I know that if I update my workflow library and ask David to update the description in the relevant thread, he'll do it super-fast, he doesn't regularly verify whether the libraries/utilities listed there are up to date/still work/are still supported.

 

Similarly, the "official" thread on Alfred's XML format is both long and incomplete. You can read all 5+ pages of it, but you still won't be fully informed of the ins-and-outs of the format because it hasn't been kept up to date.

 

The Alfred team have not done a great job of documenting Alfred for users/workflow authors. Nevertheless, Alfred has a very active, knowledgeable and helpful community, and (given the less than stellar quality of "official" documentation so far) it makes sense for the Alfred team to leverage that community to help provide quality documentation.

 

Alfred needs a wiki, sooner rather than later. Andrew, Vero and David can sit back and largely just moderate that, just as they do the forum, while Alfred's power users do most of the work of keeping it up to date (and experience shows they will).

 

The way I see it, like with a workflow directory and auto-update mechanism (which Shawn stepped in to implement, when Andrew didn't), it's probably going to happen anyway.

 

The question is probably whether the Alfred team want to have any influence over it or are happy to have it taken entirely out of their hands.

Edited by deanishe

Share this post


Link to post

So, why not go Help from the Apple menu whereby you get swept away with super jet speed to the Welcome to the Alfred v2 Support site that for the most part provides a plethera of headnumbing information.

Oh, and it's also a colourful site.

Share this post


Link to post

That's pretty good for users. The cheatsheet is very handy.

 

The developer docs on writing workflows, however, are lacking. In particular, the page documenting Script Filters (the complex bit) only contains a reference to this forum.

 

There is no correct and exhaustive explanation of the XML format anywhere (the included example workflow is incomplete, as is the stickied thread on the forum). The two included example script filter workflows contain escaping bugs :(

Share this post


Link to post

I see you've deleted the thread for contributions regarding the documentation…

 

The new Script Filter docs on support.alfredapp.com are much improved.

 

A few observations:

 

  • There's no mention that arg can also be a tag as well as an attribute.
  • Also no mention of text encoding. Given how often that comes up on the forum as a problem, it surely deserves at least a mention if not an entire section.
  • The "Escaping the XML" advice is also somewhat misleading, which is to say it implies that it's easy, which it isn't. A proper XML library should always be used. If an appropriate coding isn't specified (as in the example) and the XML contains non-ASCII characters that aren't properly encoded, bad things will happen.
  • Escaping options (for the Script box) are not mentioned at all. These differ greatly between languages and the way those languages are used. If they aren't right, bad things will once again happen.
  • No mention of how the various parameters interact. For example, what gets copied/large-texted if a copytext or a largetext isn't specified?
  • The "Result Ordering and the UID" section of the Script Filter docs starts "It's worth iterating that Alfred learns usage of your <item> results …". I guess that should be  "reiterating" or "repeating".
Edited by deanishe

Share this post


Link to post

I'd argue for the creation of a wiki for Alfred documentation.

 

This forum is a great Q&A resource for users and developers, but as noted above, it is far from ideal as a source of documentation or as a directory of workflows. Shawn's Packal has already solved the second problem,  but the documentation for users and developers is a mess.

 

I'm still open to actually doing something with the "documentation" part of Packal and making that into a user-editable wiki if people are interested in working on that. I still need to figure out the best way to go about it, but if there is interest, then I'll put some time into it.

Share this post


Link to post

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Guest
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

×
×
  • Create New...