I didn't know where else to put this, so I just decided to put it in General Chat!
Anyways, I was exploring AutoHotkey's wiki (http://www.autohotkey.com/wiki) and noticed how bare it is. The only things of interest on it are: list of commands (although the documentation has much more details for each), list of scripts (very useful, but needs more work), very few (and short) tutorials, and a list of Windows hotkeys.
The main things I think the wiki is missing is:
- The same information as the official documentation (eg. all the parameters, remarks, etc... for each command from the documentation)
- A better organization of scripts and examples. For example, instead of having a page full of script links, why not actually creating pages with relevant titles containing the full script. This way it'll be easier to search stuff.
- Better detailed tutorials aimed at the extreme novice, as well as (advanced) tutorials on certain aspects of AHK programming (like the one for SendMessage) (like dllcalls, structures, regex, etc...)
I am definitely willing to work on this, but I just want to see what the general community feeling is about those ideas. What purpose do you guys see in the wiki? Is it worth it to duplicate all the info already in the documentation? Should the wiki be only for tutorials and useful scripts?
The AutoHotkey wiki
Started by
TheGood
, Dec 24 2008 09:18 PM
8 replies to this topic
#2
jaco0646
-
- Fellows
-
- 3163 posts
Posted 24 December 2008 - 11:29 PM
A couple threads you may be interested in reading:
:arrow: AutoHotkey Wiki
:arrow: The AHK wiki needs YOU!
I don't think adding the official documentation to the Wiki sounds very beneficial, and should be the lowest priority. Any enhancements to the Script Listing would be most welcome (at least by me) and should be a high priority. I would consider better tutorials to be the highest priority, since it is the most requested feature; but it is the most difficult since someone has to write the tutorials; and ideally they should be proofread as well.
I know from threads in the past that opinions on the Wiki range from, "I love it. Give me more," to "It should be deleted," to "We have a Wiki?" There is a very broad range, but I think everyone agrees that it's under-utilized. The thing holding it back is a lack of volunteers (no surprise). I'll add more comments here as I think of them.
:arrow: AutoHotkey Wiki
:arrow: The AHK wiki needs YOU!
I don't think adding the official documentation to the Wiki sounds very beneficial, and should be the lowest priority. Any enhancements to the Script Listing would be most welcome (at least by me) and should be a high priority. I would consider better tutorials to be the highest priority, since it is the most requested feature; but it is the most difficult since someone has to write the tutorials; and ideally they should be proofread as well.
I know from threads in the past that opinions on the Wiki range from, "I love it. Give me more," to "It should be deleted," to "We have a Wiki?" There is a very broad range, but I think everyone agrees that it's under-utilized. The thing holding it back is a lack of volunteers (no surprise). I'll add more comments here as I think of them.
#3
TheGood
-
- Members
- 589 posts
Posted 25 December 2008 - 07:55 AM
OK, from the threads you posted (thanks!), it seems like there's no interest in adding all the commands from the documentation. The other thing I saw is that it might be too much work to post actual scripts there instead of forum links. Is that correct? Personally, I do agree that the commands from the docs shouldn't be merged since the documentations do such an amazing job already at explaining them. In fact, I think all the command pages should be removed because they're simply useless (they're all one-liner articles that don't even explain the parameters).
I think the wiki should only cover scripts and tutorials. For everything else, there's the official documentation, and the forum. The wiki is a great platform for the community to store and retrieve useful scripts. It is much more user-friendly than the forum, not only for the one searching the scripts, but also for the one writing them. One thing that would help there is proper syntax highlighting.
The one problem I see with adding scripts is the long process of communicating with the original authors to see if they don't mind their script on the wiki. Because of that, maybe it is better to simply give a link to the forum post. I don't know. Scripts should also be organized in a more efficient way. I'll be brainstorming for the night and see if I come up with any ideas in the morning. And of course, tutorials would be great. I think I'll start one aimed towards those completely new to programming in general.
I think the wiki should only cover scripts and tutorials. For everything else, there's the official documentation, and the forum. The wiki is a great platform for the community to store and retrieve useful scripts. It is much more user-friendly than the forum, not only for the one searching the scripts, but also for the one writing them. One thing that would help there is proper syntax highlighting.
The one problem I see with adding scripts is the long process of communicating with the original authors to see if they don't mind their script on the wiki. Because of that, maybe it is better to simply give a link to the forum post. I don't know. Scripts should also be organized in a more efficient way. I'll be brainstorming for the night and see if I come up with any ideas in the morning. And of course, tutorials would be great. I think I'll start one aimed towards those completely new to programming in general.
#4
jaco0646
-
- Fellows
-
- 3163 posts
Posted 25 December 2008 - 06:09 PM
Yes, and redundancy with the forum sounds like a maintenance nightmare (because the Wiki would end up having deprecated versions of scripts).it might be too much work to post actual scripts there instead of forum links. Is that correct?
That's a lot of material to delete; but I agree it's useless. I guess I'm not opposed to removing it and just leaving a link to the official documentation.I think all the command pages should be removed because they're simply useless (they're all one-liner articles that don't even explain the parameters).
I'm all ears (eyes?).Scripts should also be organized in a more efficient way.
#5
JoeSchmoe
-
- Members
- 304 posts
Posted 02 January 2009 - 01:07 AM
Hi, TheGood and Jaco,
I agree that the commands list at the Wiki is a little pointless. Chris did an awesome job on the AHK documentation, and there doesn't sem to be enough enthusiasm that we would ever get to the point with the wiki that it would be worth checking. It seems like a shame, but I think that that whole page of commands should be removed from the front page of the wiki and somehow archived.
Likewise, I think that links to forum posts sounds great rather than including whole scripts. Where I think value could be added is in writing short (1-3 sentence) descriptions of the scripts that are being linked to. That would help the reader figure out which scripts s/he wanted to click through to and read more about.
The key to a successful wiki, I think, is having something that people will keep on referring to. If we have something that people find helpful, they will want to give back. I think that a high quality script listing and tutorials could both do that, though not without more community involvement. We certainly don't seem to have the critical mass at this point.
Are you still working on that tutorial? Are you still interested in working on the Wiki?
JS
I agree that the commands list at the Wiki is a little pointless. Chris did an awesome job on the AHK documentation, and there doesn't sem to be enough enthusiasm that we would ever get to the point with the wiki that it would be worth checking. It seems like a shame, but I think that that whole page of commands should be removed from the front page of the wiki and somehow archived.
Likewise, I think that links to forum posts sounds great rather than including whole scripts. Where I think value could be added is in writing short (1-3 sentence) descriptions of the scripts that are being linked to. That would help the reader figure out which scripts s/he wanted to click through to and read more about.
The key to a successful wiki, I think, is having something that people will keep on referring to. If we have something that people find helpful, they will want to give back. I think that a high quality script listing and tutorials could both do that, though not without more community involvement. We certainly don't seem to have the critical mass at this point.
Are you still working on that tutorial? Are you still interested in working on the Wiki?
JS
#6
JoeSchmoe
-
- Members
- 304 posts
Posted 02 January 2009 - 01:48 AM
Just found the following tutorial specifically designed for newbies:
<!-- m -->http://www.autohotke... ... 04&start=3<!-- m -->
Found it here:
<!-- m -->http://www.autohotkey.net/~jaco0646/<!-- m -->
I think that that illustrates the weaknesses of a forum and the role that a wiki can play: there is lots of content on the forum, but finding it (or sifting through a thread that is 20 pages long) is a huge pain. A wiki could distill the most helpful stuff and be a central repository where people could look for content.
JS
<!-- m -->http://www.autohotke... ... 04&start=3<!-- m -->
Found it here:
<!-- m -->http://www.autohotkey.net/~jaco0646/<!-- m -->
I think that that illustrates the weaknesses of a forum and the role that a wiki can play: there is lots of content on the forum, but finding it (or sifting through a thread that is 20 pages long) is a huge pain. A wiki could distill the most helpful stuff and be a central repository where people could look for content.
JS
#7
TheGood
-
- Members
- 589 posts
Posted 02 January 2009 - 04:51 PM
Unfortunately, I'm not working on the wiki right now (I am working on a script though 
). But when I will have time, I will definitely want to contribute. I totally agree with you. The forum contains so much information that is not easily accessible (and the search tool doesn't always work well). And a more detailed script listing definitely sounds like a good idea.
I have to go right now, but I'll come back to see what parts I can take up and fix, or how we should try to start working on it.
). But when I will have time, I will definitely want to contribute. I totally agree with you. The forum contains so much information that is not easily accessible (and the search tool doesn't always work well). And a more detailed script listing definitely sounds like a good idea.I have to go right now, but I'll come back to see what parts I can take up and fix, or how we should try to start working on it.
#8
JoeSchmoe
-
- Members
- 304 posts
Posted 02 January 2009 - 05:25 PM
Sounds good.
I had a couple of other ideas. The first would be to post in the Ask for Help forum, asking for suggestions of tutorials or posts that people often link people to in response to questions. We could then add links to these to the list of tutorials, perhaps including some comments in the list of tutorials in order to guide people. I'm always impressed by how active that forum is, and I bet that the frequent posters would have a lot of ideas for content to link to. (like, they might have come up with that tutorial I linked to in my last post. I'm pretty sure that Tank wrote a COM tutorial and I bet that there already are other helpful tutorials, but that they just get lost on the forums)
Another idea would be for the two of us to make our own "standard library" and post it there. It seems like there was a big project to make a standard library at one point, but that it died on the vine. We can't claim to be "the" standard library, but we can definitely put something up (possibly asking some senior forum members for suggestions) as "our" standard library. I bet that it could be really helpful to newcomers, who might might not have a good sense of the "best of" functions out there.
I imagine this "nonstandard standard library" being like a linux distribution. As far as I know, there isn't a single official linux distribution that Linus endorses. Instead, individual people/entities just started making them, and the result has been very successful. Putting our stdlib on the wiki could prevent it from getting lost over time. Just as with linux distributions, if we eventually found that we had different visions for our stdlib, we could "fork" the distribution and each build our own as we wish.
JS
I had a couple of other ideas. The first would be to post in the Ask for Help forum, asking for suggestions of tutorials or posts that people often link people to in response to questions. We could then add links to these to the list of tutorials, perhaps including some comments in the list of tutorials in order to guide people. I'm always impressed by how active that forum is, and I bet that the frequent posters would have a lot of ideas for content to link to. (like, they might have come up with that tutorial I linked to in my last post. I'm pretty sure that Tank wrote a COM tutorial and I bet that there already are other helpful tutorials, but that they just get lost on the forums)
Another idea would be for the two of us to make our own "standard library" and post it there. It seems like there was a big project to make a standard library at one point, but that it died on the vine. We can't claim to be "the" standard library, but we can definitely put something up (possibly asking some senior forum members for suggestions) as "our" standard library. I bet that it could be really helpful to newcomers, who might might not have a good sense of the "best of" functions out there.
I imagine this "nonstandard standard library" being like a linux distribution. As far as I know, there isn't a single official linux distribution that Linus endorses. Instead, individual people/entities just started making them, and the result has been very successful. Putting our stdlib on the wiki could prevent it from getting lost over time. Just as with linux distributions, if we eventually found that we had different visions for our stdlib, we could "fork" the distribution and each build our own as we wish.
JS
#9
jaco0646
-
- Fellows
-
- 3163 posts
Posted 03 January 2009 - 12:48 AM
I bet that the frequent posters would have a lot of ideas for content to link to. (like, they might have come up with that tutorial I linked to in my last post. I'm pretty sure that Tank wrote a COM tutorial and I bet that there already are other helpful tutorials, but that they just get lost on the forums)
I think that that illustrates the weaknesses of a forum and the role that a wiki can play: there is lots of content on the forum, but finding it (or sifting through a thread that is 20 pages long) is a huge pain. A wiki could distill the most helpful stuff and be a central repository where people could look for content.
:? Unfortunately, you've just illustrated a weakness that belongs to both the Forum and the Wiki: people have to look for content. It will always be easier for people to ask for help rather than try to help themselves, no matter how well organized the documentation is. My tutorial and Tank's are already posted on the Wiki. :wink:
