Documentation and scanning guidelines

[OpenScanEu]

@sokol07 @OpenScanFan @minimaker-nl @xsiriox
Even though improving the firmware is a never-ending task, I have the feeling, that it is time to start the documentation (since I do not see any upcoming major changes). What do you think?

Could you maybe cross-read the current version and add/change anything you don't like ?
See https://github.com/OpenScanEu/OpenScan2/blob/main/HowToUse.md

Thank you so much and best regards,
Thomas

[minimaker-nl]

Hi Thomas, I'll have a look as soon as I can. Bye, Ming-Hua --Sent from my Android phone with mail.com Mail. Please excuse my brevity.On 26-04-2022, 18:22 Thomas ***@***.***> wrote: @sokol07 @OpenScanFan @minimaker-nl @Siriox Even though improving the firmware is a never-ending task, I have the feeling, that it is time to start the documentation (since I do not see any upcoming major changes). What do you think? Could you maybe cross-read the current version and add/change anything you don't like ? See https://github.com/OpenScanEu/OpenScan2/blob/main/HowToUse.md Thank you so much and best regards, Thomas —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>

[minimaker-nl]

Hi Thomas,   I just read through it, and here are some quick remarks.   - "(alternatively, you can connect to http:// + IP with the local IP of the device)" - Perhaps you could copy or link the instruction on using angryIP for finding the local IP. I had to do this the last time I installed the software on my laptop.   - "(please follow how to get good scanning results, to properly prepare your object and setup and avoid disappointing results :))". Perhaps "so you can avoid disappointing results" to avoid a double "and"? Just to make the sentence flow better.   - In the "how to get good scanning results" table. At "are there blurry/out...." ->  Yes:  Top bar says "increse" instead of increase.   - In the "how to get good scanning results" table. Misconception section. First and last line start with a lower case instead of high case.   - In the Troubleshooting section:    - "and you can set the starting position" - Perhaps "You can set the starting position"   This is just a quick scan, but I hope it helps. Bye, Ming-Hua   Sent: Tuesday, April 26, 2022 at 6:22 PM From: "Thomas" ***@***.***> To: "OpenScanEu/OpenScan2" ***@***.***> Cc: "minimaker-nl" ***@***.***>, "Mention" ***@***.***> Subject: [OpenScanEu/OpenScan2] Documentation and scanning guidelines (Discussion #34)   @sokol07 @OpenScanFan @minimaker-nl @Siriox Even though improving the firmware is a never-ending task, I have the feeling, that it is time to start the documentation (since I do not see any upcoming major changes). What do you think? Could you maybe cross-read the current version and add/change anything you don't like ? See https://github.com/OpenScanEu/OpenScan2/blob/main/HowToUse.md Thank you so much and best regards, Thomas — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: ***@***.***>

[sokol07]

@OpenScanEu, I looked through the documentation and, honestly, I have no idea what could be changed in it!

If there is something I could suggest I'd point a few points in OpenScan assembly instructions (I remember they were not very clear to me in a few points) - I'll write about that later, because I need to get back to the docs and find what was problematic for me.

Moreover, I'd add some useful links to the docs - link to the subreddit of the project, link to assembly instruction, link to image download etc - I'd also share the github link somewhere on the Openscan webapge as this is the main and most direct resource of information. No matter where people will find themselves, they will be guided to further resources.

Speaking of the webpage - links for OpenScan Classic manual (https://www.openscan.eu/openscan-classic) in English and German are mistaken - the "Manual (EN)" link leads to German file.
Also, the "scanner - build instruction and troubleshooting" link on the English doku website (https://en.openscan.eu/doku) is leading to the main page, not to the instruction.

[sokol07]

As I said, I looked through the assembly docs and I have a few remarks.
First of all - if you open the OpenScan classic page (https://www.openscan.eu/openscan-classic) it's quite hard to find the manual for using with RPi shield (which is a flagship solution I guess?). I know that the link is there but I think it just should be more visible. Maybe three buttons side by side:

1. Mechanical manual
   2a. Arduino shield
   2b. RPi shield
   I'd separate the Arduino assembly instruction from the Classic mechanics assembly instructions - no need for people using RPi to go through the Arduino instructions and think where the interesting thing for them begins.
   I think that link 1. should only contain information about how to assembly the frame, table and motors and whole wiring should be moved to Arduino and RPi links.

Generally speaking - in my opinion there are a bit too much links on the page and it seems cluttered when you see it for the first time - when I looking for docs (mechanical assembly, RPi docs, first how-to-use tips, software, etc) I was often redirected back to the same pages or I was opening the same documents from different places which was a bit confusing to me.

In the assembly instruction I had some problems placing the shafts. In my unit (I guess this is a matter of that particular unit) the shaft were freely rotating in the table arms but they were totally stuck (I needed to fit them with a hammer) in the stand arms. The information that the shafts should rotate freely in the stand arms should be placed earlier in the description - I hammered the shafts into the stand arms and after that discovered that they should rotate so I had to hammer them out, and drill out the holes to make the shafts movement easy. Bottom line is: I think that the information which part of the shaft should move and which one should be glued in should be placed earlier in the description. I think there should also be a hint that if the shaft isn't sliding into the holes easily you shouldn't hammer it into them but use a 6mm drill.

No moving to the RPi shield manual (https://drive.google.com/file/d/1dsRXQuZrLWvM27U1WFC0Ot8rcSIoJQud/view). I don't see any big issues with this manual, however I'd add some photos of the assembled unit to make it easier to understand which wires go where, how the flex cables and standard wires are organized in the stand, how is the RPi, shield and camera with ringlight mounted together and installed in the stand. When I was fist building the set (with Arducam) I installed it on the wrong side of the ringlight. I guess this doesn't make much of a difference, however, I think things like that should be clared to not to cause any trouble and misunderstandings.

Of course, the rest of the RPi manual should be updated according to the newest software changes (interface changes, "openscan/" instead of ip addres, etc).

Last minor change on the website - I think that the link to the blog should be placed in the main menu, not in the "community" tab - the blog isn't necessary a part of the community and the information you can find there is interesting, important and I believe that is should be easier accesible. Alternatively, maybe the "community" tab should be renamed to "more info" or something similar.

[mauricecyril]

Hi Thomas and Openscan team, I'm currently testing the image on a raspberry Pi 3B Rev 1.2 (not the 3b+). So far no issues but will report back if I encounter any errors running the pi image.