search

vasl-developers / vasl

Virtual Advanced Squad Leader
http://vasl.info/
GNU Lesser General Public License v2.1
66 stars 28 forks source link

VASL User Documentation #1868

Open derimmer opened 1 week ago

derimmer commented 1 week ago

We have four main sources of user documentation for VASL:

  1. Help files built into VASL and accessible via the Help menu during play.
  2. The VASL.info site which contains a User's Guide and several other pages which describe how to use VASL
  3. The GitHub Wiki pages, most of which deal with development issues but some of which is relevant to users.
  4. The What's New document which is part of the Help files built into VASL and which lists changes version-over-version.

We have no command-and-control processes with respect to these document sources and unsurprisingly, they are usually out-of-date and inconsistent both within themselves and between each other.

I have a couple of thoughts but would welcome discussion on how we can better manage this information.

First of all, we have been working hard to hollow out VASL.info. It's primary purpose now is to enable users to grab the latest module and extensions. The Boards, Overlays, and Scenario Setup File pages are no longer being updated. I hope to have the same success with extensions in the near future. From a documentation perspective, I would prefer to strip out the User Guide and point users to the Help Files inside VASL.

Secondly, the GitHub Wiki should be used ONLY for development / coding information and should not describe how to use VASL.

This would leave us with two active documentation streams to be managed: the Help Files and the What's New document, both of which are found in the VASL module, A best practice would be to ask developers to update these sources as appropriate whenever pulling changes into develop.

IMHO, not every PR needs to be documented in What's New. And neither do I wish to create a complete user manual. But where there is value in providing user documentation, we should do so as consistently and up-to-date as possible.

Thoughts?

geezer09 commented 1 week ago

Yeah those are good points, I will have to make some changes and decisions regarding some of this user documentation in order to automate the process of creating new releases. In order to simplify things I will probably use the Whats New document so that the same information is printed in the git releases page, the website where the download link is and the pdf accessed from VASL. We'll probably have to make some changes along the way, but the automation will allow us eventually be more consitent and thorough in updating the documentation.

derimmer commented 1 week ago

I think that is the right way to do it.