Project Documentation

I was planning on starting documenting the project today. In particular,

A user guide (for users of system showing how to use all features and interpret results)
A systems administrator guide (for administrators showing how to deploy, secure, maintain/upgrade, backup, etc.)
A developer guide (for developers showing the development workflow, high level architecture, design decision, etc.)

For this I usually use Sphinx, an excellent tool to prepare the types of docs above. Uses a markup language similar to markdown but more advanced. It can build docs to HTML and LaTeX PDF high quality outputs among other formats. While I can't find support for it in Visual Studio there is support in Visual Studio Code, microsoft's cool editor.

In addition to this, I would usually also thoroughly document at lower level directly in the source code. Doxygen is a great open source tool that supports many languages on many platforms including C#. It too can export to HTML and high quality LaTeX PDF (even typeset mathematical formula!). I will not put any Doxygen related stuff but it would be good if we can get into the habbit of nicely documenting source code (C#/TypeScript) so at some point in the future we can generate some professional high quality looking low level software docs to compliment the guides above.

Since I did not see much documentation done yet I figured this is still open for discussions. Now me it has to be one of my original deliverables so I will just go ahead and start drafting the user/sysadmin/developer guides and commit this work in docs/ since the clock is ticking.

I will include much of the stuff Brian has sent my way and any other scattered stuff produced that I come across to organise the dev docs. Andrew also will contribute especially in writing the user docs. Those docs can and should be maintained along side development the same way the code is. I'll include in the developer guide instructions for how to contribute to docs/ (installing necessary editor, installating Python, editing markup code, building output).

If you chose to use a different tool in the future I have no problem with that but time is running out and I have to choose something I can be productive with. And I also think you will like it.

Comments (4)