Improve documentation

[Guillawme]

Hello,

Every time I use Topaz, it's a struggle to find documentation. Not because of a lack of it, but because it is scattered across different documents, all these documents don't always agree or are not always up-to-date. Even more confusing is the fact that some documents don't use the same terminology for (seemingly) the same parameters, and generally they don't go into the same level of details. Lack of detail is ok to some extent: it's normal for command line help to be shorter than the tutorial; but sometimes, important info like acceptable ranges for numeric parameters or which unit is expected (Å or pixels?) is very difficult to find.

Currently, there is documentation at all these locations (at least, maybe I am still missing something):

• output of command line help: topaz --help, topaz extract --help, etc.
• several notebook files in the repository
• several README files in the repository (main file, and one in the relion_run_topaz directory)
• parameter descriptions in the GUI (topaz gui)

I would like to help improve the documentation, to the extent I am capable (not a machine learning expert, only superficial experience with Topaz). I believe it would be very helpful to have a single, primary place to look things up with all details and long-form explanations (because for people with a background in biology, like myself, the model architectures section of the README makes very little sense, but I feel I could understand it if the vocabulary was explained). The other sources of documentation (I am thinking mostly the command line help and parameter descriptions in the GUI) should also be updated to be made consistent (show the same info, which currently is not always the case: I often have to look up both the command line help and descriptions in the GUI to get complete info).

But before I spend any time working on this, I would like to ask what would be the preferred approach?

• one single file in the repository? maybe not ideal to use the main README that's also the landing page on GitHub, so should be in a distinct file
• a doc directory in the repo with one file for each command? nice because it would be versioned, but I feel like if would be somewhat redundant with command line help already written in the command line parsing logic in the source files (maybe these could be automatically extracted to pre-populate the long-form documentation, to which we could then add more details? seems like there are tools that can do that)
• the GitHub wiki? could be an easier way to get users to contribute to improving the documentation, since it can be edited without having to fork the repo, add commits and submit a PR
• something else?

I'll be happy to contribute to this when we have a plan for how best to proceed (but don't have enough time to lead the effort, unfortunately).

[tbepler]

Improved documentation is something I would love to have. A complete and expanded set of documentation in the wiki seems like the ideal case and I'm happy to accept pull requests aimed at creating this documentation.

In the meantime, ensuring consistency between the command line help, GUI, and tutorials seems like a good intermediate step to reduce possible confusion. If there are specific cases where documentation in these places disagree, I would be happy to accept pull requests correcting them. In general, the priority of correctness is probably tutorial > command line > GUI, but this may not be true for all cases.

Regarding one centralized set of documentation that can be version controlled and from which the command line help can be automatically generated or vice versa: this would be great, but I don't have experience with tools that do this. If anyone knows about or has experience with tools like that, their opinion is appreciated!

[Guillawme]

A complete and expanded set of documentation in the wiki seems like the ideal case and I'm happy to accept pull requests aimed at creating this documentation.

Looks like the wiki is not activated for this repo (clicking it takes me back to the landing page). Could you activate it and give me write permission? I am planning to start listing all options for each command and gather their documentation from the various places I listed in my first message, then put it in the wiki. That should be a good starting point to then write longer explanations next to each option.

[tbepler]

The wiki now has public write access. Let me know if you have any issues accessing it still.

[Guillawme]

I will add content to the wiki whenever I have some time. My current plan is to have one page listing all topaz commands, with links to each command's page listing options and with more detailed explanations.