jassdoc
jassdoc copied to clipboard
Issues vs Submitting incomplete descriptions
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