ChrisTitusTech / winutil

Chris Titus Tech's Windows Utility - Install Programs, Tweaks, Fixes, and Updates
MIT License
16.81k stars 1.08k forks source link

SUGGESTION: Have a place to write documentation into #2270

Closed og-mrk closed 3 days ago

og-mrk commented 1 week ago

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

  1. The initial creation of the documentation will take some time
  2. 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.
  3. Consistency across the style of writing will be a challenge, which's the same challenge with any other Technical Documentation...
  4. 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).
  5. .. 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

Real-MullaC commented 1 week ago

I would also help keep the wiki up to date as new commits are accepted into the repository.

Real-MullaC commented 1 week ago

@ChrisTitusTech Could this be sorted?