[scummvm-devel] New ScummVM Technical and User documentation guidelines

[Matan Bareket]

*tl;dr*

We have new requirements to include documentation when submitted code and
reviewing PRs. This information can also be found in the wiki
<https://wiki.scummvm.org/index.php?title=Commit_Guidelines#Documentation>.


----


Team,

Over the last 3 months, our two Season of Docs participants CadiH and
b-gent worked diligently to improve our user facing documentation
<https://docs.scummvm.org> and developer documentation
<https://doxygen.scummvm.org> respectively.

In order to maintain a high level of quality, and avoiding documentation
rot, we are adding a few requirements around code contributions and PRs.

User facing changes:

Any user facing changes should also have a DOCS commit detailing these
changes. CadH has put together a guide on the Wiki that would be helpful
here
<https://wiki.scummvm.org/index.php?title=Developer_Central#Contribution_guide_for_technical_writers>.
Example of user facing changes:

   -

   GUI Changes
   -

   scummvm.ini changes
   -

   Keymap changes
   -

   New ports
   -

   New features
   -

   New options in submenus


For PR reviewers - PRs should not be merged without the necessary changes
to documentation.

Developer changes:

Any code contributions outside of engines and backends must be accompanied
with updated doxygen style comments. This includes but not limited to:

   -

   New methods
   -

   Signature changes
   -

   Changes to existing methods
   -

   New classes


Retroactive documentation can be committed with the DOXYGEN project scope

Code contributions in engines and backends do not have a hard requirement
for doxygen style comments, but they are encouraged.

For PR reviewers - Functions and classes without the required documentation
should request those to be added before merging.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.scummvm.org/pipermail/scummvm-devel/attachments/20201209/14cdb9a9/attachment.htm>