Review DocTR documentation

[fg-mindee]

Hi again @fharper 👋

Another request for DocTR would be if you could check out the documentation and provide some feedback: https://mindee.github.io/doctr/

I'll soon make some structural changes to integrate the PyTorch-specific documentation (next to TensorFlow version), and it will be a good occasion to make other edits if necessary !

Cheers

[fg-mindee]

FYI @fharper we will do a release in a few weeks and by then, we will most likely change the README and documentation!
Would you have any idea whether/when you'd be able to provide some feedback on the README (#25) and the doc? 😁

[fharper]

I'll do it by the end of the week :)

[fharper]

As with any feedback I'm giving, keep in mind that I don't have the holy truth so feel free to disagree. I'm usually seeing every little things and since I believe the devil is in the details, I usually share them. I also focus on what could be improved IMNSHO, so don't take anything personal here. Lastly, it's based on the actual knowledge I have of this project, which is basically nothing for now (didn't take the time yet to try it, but fear not my friend, it's coming). If anything is unclear or you want to discuss any points I wrote, please let me know, I'll be more than happy to do so!

General

• I know doctr is an OSS project, but I think it would make sense to move the doc inside our main documentation. It wouldn't make sense if doctr was not mostly done by us and it wasn't under our own organisation on GitHub. Doing that will ensure the same structure for our users using both, and give some more visibility on our product for doctr users who don't know us.
• Does our target audience knows already how all this stuff works? If not the doc would need some more "taking the user by the hand" content. Example, in the index you talk about NLU, predictors and other things I have no idea what they are even if I know what OCR is and used some in the past. I may not be the target audience (yet).

https://mindee.github.io/doctr/

• No need for "Welcome to the documentation of DocTR!"
• I would change the wording of "Daily maintained" for something like "actively maintained by Mindee" which doesn't promise we push daily (which we nearly do, but we don't), and it's a small promo for us :D
• Add a Table of Content for the page at the top.
• No need for changelog & package reference since it's already in the left sidebar.
• Maybe it's because of my lack of deep knowledge on OCR, but seems like right after the Installation section, we do back into the features of the app. I would move getting started at the end. Even removed it since there is the installation menu to the left.
• Unless again the target audience knows everything in that Model zoo and supported dataset listing, I may add some more details on the benefits of that.

https://mindee.github.io/doctr/installing.html

• "This library requires Python 3.6 or higher." should point to Python doc like we do for TensorFlow or PyTorch.
• "Whichever OS you are running, you will need to install at least TensorFlow or PyTorch. " How can I know which one should I use? Is there specific cases where I should use one or another?
• "For MacOS users, you can install them as follows" we assume people have Homebrew installed (need to point them in the right direction). We can also proposed a more Python centric way as a alternative with pip.
• "For Windows users, those dependencies are included in GTK. You can find the latest installer over here." should we point to official GTW Windows installer instead?
• Add a table of content
• last code snippet of this page has a formatting problem

Tomorrow I'll check the references.

[fg-mindee]

Thanks a lot 🙏

To answer more specifically:

https://mindee.github.io/doctr/

• Add a Table of Content for the page at the top.

Considering the small number of sections in this landing page, is it really useful?

• Unless again the target audience knows everything in that Model zoo and supported dataset listing, I may add some more details on the benefits of that.

Mmmh, there are more details in the package reference, I'll try to both link the paper & the package reference for each model

https://mindee.github.io/doctr/installing.html

• "Whichever OS you are running, you will need to install at least TensorFlow or PyTorch. " How can I know which one should I use? Is there specific cases where I should use one or another?

That one is tricky: say you want to build a house, you can get the same result with material A or B. To make it profitable, you had to make a choice early on about which material to invest in (learning curve-wise). It's exactly the same thing here: half the community is more comfortable with PyTorch, half with TensorFlow. The library fully supports both

• "For Windows users, those dependencies are included in GTK. You can find the latest installer over here." should we point to official GTW Windows installer instead?

I added the reference to the most recent installer, the official versions are lagging behind unfortunately (but that one was released by a senior developer working on Microsoft projects)

• Add a table of content

Same thing here, isn't it a bit short for a table of content

The rest of your comments has been taken care of :)