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 ...
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
Hoppfrosch: Perhaps a simple "COM-introduction page" (...) might help
Lexikos : Yes, I thought so too, but haven't had sufficient motivation to write it.
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 ... :-(