Jump to content

Sky Slate Blueberry Blackcurrant Watermelon Strawberry Orange Banana Apple Emerald Chocolate
Photo

[docs] AutoHotkey_L documentation rewriting project?


  • Please log in to reply
66 replies to this topic
sinkfaze
  • Moderators
  • 6367 posts
  • Last active: Nov 30 2018 08:50 PM
  • Joined: 18 Mar 2008

Note: Beginners should simply choose the ANSI version when downloading AutoHotkey_L, to avoid most of the common compatibility issues. See Unicode vs ANSI below for an advanced explanation.


I don't see the point in such a note since:

[*:2v04u5mx]As has always been the case (and is even more clear in the docs now) beginners barely have anything to worry about in terms of compatibility issues, and
[*:2v04u5mx]I would hardly expect a beginner to start reading the documentation until they've already downloaded the program. If they download AHK then have that surprise sprung on them in the documentation, you've just confused the user enough that they might not use it.

fragman
  • Members
  • 1591 posts
  • Last active: Nov 12 2012 08:51 PM
  • Joined: 13 Oct 2009
New users are likely coming from a non-AHK background and can thus start with the better Unicode version as they don't need backwards-compatibility. Users who already use AHK for a while are likely to have more experience to make the decision for themselves.

Almost every program nowadays is written in Unicode, anything else as default would just be a step backwards.

fischgeek
  • Moderators
  • 1074 posts
  • Last active: Jul 07 2015 06:27 PM
  • Joined: 20 Apr 2009
Not sure if I'm going off topic here or not, but I would really like to see a lot more documentation surrounding all things COM.

IsNull
  • Moderators
  • 990 posts
  • Last active: May 15 2014 11:56 AM
  • Joined: 10 May 2007

Not sure if I'm going off topic here or not, but I would really like to see a lot more documentation surrounding all things COM.

Well COM is documented very well on several MS pages, AHK_L just points out some AHK related things.

I agree that there could be a more general introduction and a better outlining of weird things (COM Arrays for example), using COM requires a basic understanding of it. I would therefore add some links to msdn where people interested in it can read about it.

While I think COM is cool and all for Office integration, providing native integration for the .NET environment would be the future.

hoppfrosch
  • Members
  • 399 posts
  • Last active: Feb 26 2016 05:31 AM
  • Joined: 25 Jan 2006
Nion wrote here:
[quote name="Nion"]I think github should be used for keeping track of all the updates people contribute, but I agree with you that it might be not easy for users that don't even know git to use github to contribute any of their work.
So I would volunteer to accept contributions by any user (either per mail or per pm here in the forums) and push them to github for them, so everybody can access the current state of the documentation at a central place, which is the git repository.

Additionally, we should have a clear what-to-do list in this repository, where everybody can see which pages of the docs need to be updated and which are currently being updated by other people. Maybe we should even go further and add the names of the people currently working on an update for a page, so others can get in touch with them to provide any help (this would be best if done over irc or a separate thread or just through the pm system).

It would be great if some users who are currently learning how different things work with AutoHotkey's syntax (especially Objects as said previously) could ask their questions in a separate thread so that people working on the docs can see which parts need to be improved.

Of course, I will provide any help to improve the docs or write more examples, but I would like to first get a good plan of how to organize the process instead of people now starting to update the doc pages on their own and probably many doing the same work at the same time.[/quote]
Those have been exactly my thoughts. Therefore I started a Trello project to organize the work on documentation (see: https://trello.com/b...c442e040466599d)

Actually I did some simple corrections on current AHK-documentation and generated some pull requests to Lexikos, some of them have already be merged in documentation.

The trello board should manage the following:

[*:22rwb0vh]Proposing changes to documentation - gathering ideas on possible changes[*:22rwb0vh]Discussing, whether those changes should be implemented (maybe a link to discussion page in forum?)
[*:22rwb0vh]After "accepting" the suggested change it's ready to be implemented
[*:22rwb0vh]Any member of the board who is willing to do the change picks out the card and assigns it to himself - this way anybody can see who's actually doing the work (and every board member can join the work ...). I think the trello board is not appropriate to do the technical discussion on the exact "doing" of the change (for example: discussing which is the best example for metafunctions?)
[*:22rwb0vh]After doing the work a review of the document should be done by some editors (contents, formatting, wording (correcting NOOB-english speakers like me ;-)) ...). Also every board member who's interested could participate in review process[*:22rwb0vh]A pull request is created
[*:22rwb0vh] the "documentation owner" (Lexikos and some other qualified people) does the final review on pull request
[*:22rwb0vh]Suggested enhancements are considered in pull request by person who creates the pull request -> final review again
[*:22rwb0vh]Changes/Pull Request is merged into documentationBy assigning people to the cards and having different card status, it's quite clear to see who's doing when what ...

I think a process like this is needed to grant a high quality documentation and allow cooperation of many contributors - I don't know wheteher it's the best way to do it, but it's a least a try which sounds reasonable for me ...

As I'm using git - and I'm the only one who contributes at the moment, the process is quite easy: I suggest - Lexikos and others (fincs for example, myself) discusses (sometimes) - I do the changes on a branch of my github clone - I create a pull request - Lexikos reviews - I do the suggested changes - and lexikos pulls the changes.

Currently we (Lexikos and me) still figure out how the pull requests and the containing changes should be structured to be easily merged into documentation:
[*:22rwb0vh]formatting of the HTML (which CSS styles to use when (for example))[*:22rwb0vh]formatting guidelines for examples (One true brace (OTB) Notation? Indentation, ...)[*:22rwb0vh]clearly separating different changesets in different commits (for easier final review when merging ...)[*:22rwb0vh]...As this is still a work in progress, there's no real documentation ("Documentation contribution guildelines") on this yet (beside some comments on pull requests, where Lexikos gave me some hints, what to make better to allow him easier merging (that means: what to do to allow merges with least effort for Lexikos)).

Feel free to join the board - any board member can invite you to become a member. Just ask ...

[quote name="Jeremiah"]
Not sure if I'm going off topic here or not, but I would really like to see a lot more documentation surrounding all things COM.[/quote]
That's something I suggested yesterday to Lexikos

[quote name="https://github.com/Lexikos/AutoHotkey_L-Docs/pull/38#issuecomment-7974025"]
Hoppfrosch: Perhaps a simple "COM-introduction page" (...) might help
Lexikos : Yes, I thought so too, but haven't had sufficient motivation to write it.
[/quote]
Anybody who's willing and has the capabilities to do it is welcome to provide such pages ... ;-)

It's a pity that some of the work already done within this thread was located on Autohotkey.net - and seems to be gone due to the recent problems with the site ... :-(

IsNull
  • Moderators
  • 990 posts
  • Last active: May 15 2014 11:56 AM
  • Joined: 10 May 2007
Using git (GitHub) under windows becomes very easy since GitHub has released a very beginner friendly Tool:
GitHub for Windows

fischgeek
  • Moderators
  • 1074 posts
  • Last active: Jul 07 2015 06:27 PM
  • Joined: 20 Apr 2009

Well COM is documented very well on several MS pages, AHK_L just points out some AHK related things.

While it is documented well on MSDN, I'm thinking more AHK related documentation. Expecially with example code. Often times I look in MSDN for things related to COM, DllCall, etc. but it's difficult for me to sometimes translate them back into what I want AHK to do with those things. RaptorX has a good thing going with his AHKTuts, but I'm not sure how many he can put out there being only one man. Jethrow, tank, and sinkfaze all have put out fantastic documentation in the past surrounding COM/iWeb. Jethrow has even updated his documentation to fit _L and without it, I would've been lost. I'm just saying I would like to see COM (for Office and IE) make it into the AHK Help File.