Improved documentation

(Guillaume Klein) #1

Documentation is important for project like OpenNMT with many options and complex behaviors. I spent the last few days revisiting the documentation to make it centralized and clearer for a better reading and updating experience:

An important aspect is that the documentation is now part of the main code repository. That means from now on, you’ll find documents that match your code version at all times and we’ll ensure that new PRs update them accordingly (when it applies).

The documentation also includes a user-friendly generated listing of available options. See for example the options of train.lua.

Hopefully, this documentation will grow by covering more use cases and providing useful information on how OpenNMT works.

(Steve Braich) #2

Hi Guillaume,
Thank you for the improvements. May I recommend a section in the new documentation for installation? I don’t see one.

I found the old documentation for installation to be somewhat fragmented. Some parts are in the FAQ which I find odd and the quickstart guides are no longer there. Also, I believe there is a typo (at least from my limited experience) in the FAQ installation:
sudo nvidia-docker run -it harvardnlp/opennmt:8.0 .
I was advised to remove the “.” at the end, which solved my problem.

I can assist with the installation documentation, if that would be helpful. It would definitely improve my competency with this tool and others might benefit.


(jean.senellart) #3

Hi @stevebpdx - glad to see you here. Installation documentation section will be welcome - could you propose a PR?

(Steve Braich) #4

Hi Jean. I would be glad to, except I don’t know what a ‘PR’ is in this context. Peer Review?

(jean.senellart) #5

It is a a Pull Request - it means that you fork the project on your github account. Create new content or fix the existing one and then create a “Pull Request” (PR) so that we can review and integrate - see as a quickstart on github.

(Guillaume Klein) #6

Good point. I moved the installation procedure in the documentation:

Feel free to improve or complete it by clicking on the “Edit on GitHub” link at the top. GitHub should then walk you through the pull request procedure.

(Steve Braich) #7

Thank you Jean! I am familiar with source control. Actually never heard someone say ‘PR’ in reference to it.

I will start on this soon. I want to get a little more experience under my belt. I need a fresh machine to test the documentation on. There were a couple of gotchas, for me anyways.