Have a place to Contribute Documentation to, whether through GitHub Wiki, or by generating a Static Site through Markdown Files (.md Files, or using a more advanced Markdown format, like AsciiDoc .adoc Files).
Advantages
This will provide a source of knowledge that Contributors can point to for new comers, and Users who're trying to understand and/or use the tool.
Disadvantages
The initial creation of the documentation will take some time
The maintenance of such documentation will be takeing-up Contributor's time, when for example, making Medium/Huge code changes or additions, or when making a full re-write to workflows (Like the app install workflow, and how things generally work).. the documentation will be out-of-sync with the code base, so we'll need to update the docs as frequently as possible.
Consistency across the style of writing will be a challenge, which's the same challenge with any other Technical Documentation...
There'll be some areas that's harder to contribute to then others, as not everyone is knowledgeable enough to write clear and concise documentation on that area, or they might not have the time to do so.. one example comes to my mind is write Full Documentation on how the UI Code is structured, and What each element is (of course using & linking Microsoft Docs for each element).
.. Who will write Documentation? I know this may sound stupid on my part.. but the fact is, Programmers are generally not into writing Technical Docs, which's understandable..
And one way I thought of is, after completing the docs for WinUtil, force every PR to update the docs if it's needed (and the docs to update is, of course, related to their PR changes.. and some docs for things outside the changes, if it's seen as needed...).
This will make future maintenance easier for everyone 👍
.. Quite a few downsides compared to advantages 😆, but the fact is.. all of this headache is worth it at the end, or so I believe.. and I think other contributors can agree with me on this part.
Additional Info
This was initially opened by @Marterich in his Discussion Thread back in May of this year, but I created this Issue Ticket to bring light onto Marterich's suggestion, as Documentation is by far the most needed thing in the project, at least IMHO.
The suggestion/idea "In a Nutshell"
Have a place to Contribute Documentation to, whether through GitHub Wiki, or by generating a Static Site through Markdown Files (
.md
Files, or using a more advanced Markdown format, like AsciiDoc.adoc
Files).Advantages
This will provide a source of knowledge that Contributors can point to for new comers, and Users who're trying to understand and/or use the tool.
Disadvantages
.. Quite a few downsides compared to advantages 😆, but the fact is.. all of this headache is worth it at the end, or so I believe.. and I think other contributors can agree with me on this part.
Additional Info