Issues vs Submitting incomplete descriptions

[Luashine]

One of my pressing reasons, to move Lucan's Frames doc here and to link every undescribed function from moyacks jassdoc -> here, was to "unify" the search. To not waste time researching something that already has been described before - without you knowing it, because you couldnt find. There's now one fewer place to look in for documenation. Side note: I was going at a speed of ~25s per link, quite good ^_^ and fast enough to not bother with a script yet

With that done, there's now the issue of issues that are opened on Github. Their info appears neither here nor there, creating yet another place to look up the information. My idea is to get rid of them use them less. Anything that's a long-standing WIP or where the author takes a break, should go straight into the doc as it is, encouraging people to complete a description later (when they want to).

Good example: #27 has been hanging there for 2.5 years. Let question marks be question marks, i.e. "its something!"

Anti example: On the other hand #31 has no value in a doc until it's complete. Maybe add a tag for such notes? @wip https://github.com/lep/jassdoc/issues/31 -> "This function's description is being worked on, you can help! "

This is a different kind of thinking, becoming more agile (though not the literal agile haha). A partial documentation can be helpful in itself. A beginning of a description (a stub in Wikipedia's terms) can be helpful to motivate people to complete it, avoiding the blank sheet problem.

This won't become a professionally polished documentation so I would not bother trying to reach perfection. I myself try to go in-depth but I expect most people won't, yet even minimal answers can be enough:

Question: anyone know what ResetTrigger does? Answer: clears execution/evaluation count of the trigger Reply: interesting

[lep]

I do like the @wip tag link. But I'm unsure how to best get it into the DB/the web interface. Thinking about it i should probably already link to wc3modding.com from the web interface, so there wouldn't be a need to add w3modding links to the DB. Done. For GitHub only linking to PRs could be nice as the first (or second) commit could be to add the tag to the PR itself and then work in that PR.

(Also wc3modding could embed the sqlite file if they wanted aswell :)

On 21.04.22 19:19, Luashine wrote:

One of my pressing reasons, to move Lucan's Frames doc here and to link every undescribed function https://wc3modding.info/6421/functions-getsoundisplaying/ from moyacks jassdoc -> here, was to "unify" the search. To not waste time researching something that already has been described before - without you knowing it, because you couldnt find. There's now one fewer place to look in for documenation. Side note: I was going at a speed of ~25s per link, quite good ^_^ and fast enough to not bother with a script yet

With that done, there's now the /issue of issues/ that are opened on Github. Their info appears neither here nor there, creating yet another place to look up the information. My idea is to get rid of them use them less. Anything that's a long-standing WIP or where the author takes a break, should go straight into the doc as it is, encouraging people to complete a description later (when they want to).

Good example: #27 https://github.com/lep/jassdoc/pull/27 has been hanging there for 2.5 years. Let question marks be question marks, i.e. "its something!"

Anti example: On the other hand #31 https://github.com/lep/jassdoc/issues/31 has no value in a doc until it's complete. Maybe add a tag for such notes? @.*** https://github.com/lep/jassdoc/issues/31| -> "/This function's description is being worked on, you can help!/ "

This is a different kind of thinking, becoming more agile (though not the literal agile haha). A partial documentation can be helpful in itself. A beginning of a description (a stub in Wikipedia's terms) can be helpful to motivate people to complete it, avoiding the blank sheet problem.

This won't become a professionally polished documentation so I would not bother trying to reach perfection. I myself try to go in-depth https://wc3modding.info/pages/jass-documentation-database/class/functions/query/TimerStart/ but I expect most people won't, yet even minimal answers can be enough:

Question: /anyone know what ResetTrigger does?/
Answer: /clears execution/evaluation count of the trigger/
Reply: /interesting/

— Reply to this email directly, view it on GitHub https://github.com/lep/jassdoc/issues/45, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAA3SWJBZFO7ZOZWKWAYUODVGGEZLANCNFSM5T74YZBA. You are receiving this because you are subscribed to this thread.Message ID: @.***>

[lep]

I think i don't like writing TODO in the docstring itself. But putting a normal jass comment //TODO like before the docstring should be clear enough. That way i think it still feels nice enough to publish it on the web interface.