The documentation is so bad...

proton258
Posts: 9
Joined: Tue Mar 19, 2019 7:50 pm

The documentation is so bad...

Post by proton258 » Sat Apr 13, 2019 6:20 pm

Hi Bertus

Protoneer sell a product without appropriate supporting documentation on that product...why is this and why can you not put together a better configuration guide for your products. The amount of posts on the forum seeking guidance on setup and configuration seems to bear this out?

There are some very simple things you could explain in the documentation for new users trying to setup the board and get stepper motors working etc

1) if you are using Pololu a4988 stepper drivers connected to a 2.58 board you can directly wire the stepper motor wires into the green connector blocks for the X, Y, Z or A axis. It took me a long time to work this out...way to long. Nothing in your documentation explains this relevant piece of information.

2) When using Pololu a4988 or similar stepper driver you need to power them using an external power supply, so you connect the DC+ to the 12-30 VDC output and then you connect the DC- to the GND, however it is confusing when you do not mention or explain that the DC- is acting as GND.

3) if you are going to use external stepper drivers on the 2.58 board you either need to solder the relevant wires to the board or use the Pololu Socket To External Driver conversion board...however the documentation on the two different configurations is sadly lacking in the extreme

4) Documentation on the schematics, setup and configuration of the 2.58 board is totally lacking...

I have finally got my 2.58 board up and running and bCNC now controls my three stepper motors...however it has taken me way to long to get the configuration up and running and i have had to watch to many YouTube clips to work out what i need to do to achieve a working solution...can you not put together a proper step by step configuration guide and help all the people that want to use your products...if i new it would spend so much time getting to this stage on my CNC journey, I would have purchased a different product.

Seriously frustrated...

erniehatt
Posts: 292
Joined: Thu Nov 03, 2016 8:16 am

Re: The documentation is so bad...

Post by erniehatt » Sat Apr 13, 2019 11:25 pm

I must say I agree to a certain extent, but most of the questions have been answered here on the forum at some stage or other, just a matter of searching.
Generally one starts a forum to cover such questions, If you ask a question here then Bertus will always answer, though it does take about a week, depending on when you ask.
I never once had to resort to you tube videos.
The only thing I find that needs some explanation is setting up end stops, have never been able to get these working, so have left them unconnected.

tcurdt
Posts: 3
Joined: Sun May 10, 2020 10:11 pm

Re: The documentation is so bad...

Post by tcurdt » Sun May 10, 2020 11:45 pm

Not a great sign that there is no official response to this.

I am also just getting started with my old 2.58 board and also find the amount of searching I have to do not really OK.

Not that it is relevant - but just coming to website and being created with a "Warning: preg_replace(): Compilation failed: invalid range in character class at offset 4" just says "we don't care". The contact page just points to forum. Sorry - but that's just not OK.

Bertus Kruger
Site Admin
Posts: 1649
Joined: Wed Feb 03, 2016 10:26 pm
Location: Wellington , New Zealand
Contact:

Re: The documentation is so bad...

Post by Bertus Kruger » Tue May 12, 2020 10:22 pm

tcurdt wrote:
Sun May 10, 2020 11:45 pm
Not that it is relevant - but just coming to website and being created with a "Warning: preg_replace(): Compilation failed: invalid range in character class at offset 4" just says "we don't care". The contact page just points to forum. Sorry - but that's just not OK.
What URL are you seeing this warning on? I just fixed a issue with the Wiki that might be related...

Are you talking about the contact page on the forum? (We had contact details on it but that just got blasted with spam).

Bertus Kruger
Site Admin
Posts: 1649
Joined: Wed Feb 03, 2016 10:26 pm
Location: Wellington , New Zealand
Contact:

Re: The documentation is so bad...

Post by Bertus Kruger » Tue May 12, 2020 10:39 pm

tcurdt wrote:
Sun May 10, 2020 11:45 pm
Not that it is relevant - but just coming to website and being created with a "Warning: preg_replace(): Compilation failed: invalid range in character class at offset 4" just says "we don't care". The contact page just points to forum. Sorry - but that's just not OK.
Right, I found it my blog page. Thanks.

Bertus Kruger
Site Admin
Posts: 1649
Joined: Wed Feb 03, 2016 10:26 pm
Location: Wellington , New Zealand
Contact:

Re: The documentation is so bad...

Post by Bertus Kruger » Tue May 12, 2020 11:53 pm

tcurdt wrote:
Sun May 10, 2020 11:45 pm
Not a great sign that there is no official response to this.

I am also just getting started with my old 2.58 board and also find the amount of searching I have to do not really OK.

Not that it is relevant - but just coming to website and being created with a "Warning: preg_replace(): Compilation failed: invalid range in character class at offset 4" just says "we don't care". The contact page just points to forum. Sorry - but that's just not OK.
Thanks for letting me know about the website issues.. It was actually a huge issue... :shock: :shock: :shock:

Managed to resolve it now...

Bertus Kruger
Site Admin
Posts: 1649
Joined: Wed Feb 03, 2016 10:26 pm
Location: Wellington , New Zealand
Contact:

Re: The documentation is so bad...

Post by Bertus Kruger » Wed May 13, 2020 12:03 am

tcurdt wrote:
Sun May 10, 2020 11:45 pm
Not a great sign that there is no official response to this.

I am also just getting started with my old 2.58 board and also find the amount of searching I have to do not really OK.
Documentation writing is not natural to me.... I have spent lots of time with it and still get the same complaints that its to difficultor hard to find.

MEdiaWiki also does not cut it....

Any suggestions for better documentation solutions. Keep in mind I am only one person with a day job and a second baby on the way trying to make things better.

tcurdt
Posts: 3
Joined: Sun May 10, 2020 10:11 pm

Re: The documentation is so bad...

Post by tcurdt » Wed May 13, 2020 11:12 pm

Bertus Kruger wrote:
Wed May 13, 2020 12:03 am
Documentation writing is not natural to me.... I have spent lots of time with it and still get the same complaints that its to difficultor hard to find.

MEdiaWiki also does not cut it....

Any suggestions for better documentation solutions. Keep in mind I am only one person with a day job and a second baby on the way trying to make things better.
Thanks for the response. First off - all the best for the little one :)

I guess since I am criticizing I should also give some (hopefully) constructive feedback. Let's start with a user journey:

https://protoneer.co.nz redirects to the ebay shop - weird. This should be the main page listing all the products and linking all the relevant resources for those products. But there is no clear main page. There is https://blog.protoneer.co.nz/ but it is a blog. While blog posts are fine as news section of a website (or well - blogs), they are not great as product pages. I go to https://blog.protoneer.co.nz/ and I don't even find the RPi Hat listed in the product menu!? I scroll down and find an article about the RPi Hat. I click on it. It's from 2015 - is this still up to date? The image does not look like my board. I don't have a removable arduino board!? I got version 2.58. No mention of versions. This creates confusion. The gallery doesn't show my old board either. Am I on the right page? The links to wiki are (I want to say) hidden under "Extra Links". They provide some of the most import information for people getting started. Yet it took me a while to find them. These two should be made really prominent:

Wiki page with setup details : Raspberry Pi CNC Board Wiki
Quick Start Guide

I click the link to the wiki. Finally - a board that kind of looks like the one I have. I scroll down to software. I find my board version (yay!). The text talks about a "Raspberry Pi V4.00 image" but there is no link?! What image is that? Frustrated I try the Quick Start Guide. "What you will need to get started". Cool, I could use my old Raspberry Pi B! Darn, no I cannot - it seems it needs a B+. The board does not fit on the B. OK, let's use the Pi3. "Download the pre-configured Raspberry Pi image" Hah! That must be the image! Downloading. Now running the image. Nice and convenient. Unfortunately many broken links. Software was updated - but not the links. No problem - at least for me. Fixing. Now the serial config works, so does most of the software - nice. The different GRBL versions are a bit confusing. Which one is on the board? Which one should I use. I just got to github to get latest release. Running the uploader - success.

Now let's come to my suggestions:

1. protoneer.co.nz should be your main page. It should list all products and link to a product page each. Sending people straight to a (now even disabled) ebay store - not great. Link to the shop from protoneer.co.nz
2. Have all products in the projects menu. Currently there is the Arduino CNC Shield, the More Core Shield and the GRBL library.
3. Don't (ab)use blog post for product pages. even wordpress (I assume this is what you are using) supports just "pages".
4. Each product page should have very prominent links to the resources. For the Pi Hat:
a) Quick Start
b) The Wiki
c) The Raspbian Image
5. On the product page explain the bigger picture of the board. Don't dive right into e.g. "Single Command Mode".
6. List all versions on the product page - with links to special information. Preferably show each version with an image.
7. I know support emails suck - but pointing people to a forum is not great. If you get too many improve the docs and the product. It's rare that people write to support just for fun. Maybe point them to a FAQ, have them search the forum first - but also provide a direct contact afterwards.
8. The probe section does not actually have any information. When I look at the pinout image, there is no indication at all what the probe pins are. And the original poster lists some other things. I am sure there is more. Just answer and improve the docs when people come here reporting things.
9. Whenever you mention something - link to it.
10. Who has access to the wiki? Just you? What's the point of a wiki then? Maybe use github instead? So people can send PR to the docs? Wouldn't so bad to track problem with github issues either.
11. Not responding to issues https://github.com/Protoneer/Raspberry-Pi-CNC/issues/21 is also not great. As bad as the questions might be.

I hope this was at least a little helpful.

Bertus Kruger
Site Admin
Posts: 1649
Joined: Wed Feb 03, 2016 10:26 pm
Location: Wellington , New Zealand
Contact:

Re: The documentation is so bad...

Post by Bertus Kruger » Fri May 15, 2020 1:37 am

tcurdt wrote:
Wed May 13, 2020 11:12 pm
Thanks for the response. First off - all the best for the little one :)
I appreciate your support and I am thankful for your contribution....

At the moment I am just breaking down how I am going to get this done.

I do like the idea of having the documentation as 'n github repository. Just need to work out how to make it easy to search for stuff as well.

MikeTheBiker
Posts: 3
Joined: Sun Jan 26, 2020 11:30 am

Re: The documentation is so bad... / support + docu helps you make money

Post by MikeTheBiker » Sun May 17, 2020 11:31 am

I totally agree with the previous posters. I also believe that you could charge more for your "original" board - no props from my side but the documentation must really improve. Now you compete with the Chinese manufacturers on price - you won't win. Compete on support and expertise and you will win.

BTW: A board for ESP32+grbl would be cool. You probably know there is already a SW-port on GH: https://github.com/bdring/Grbl_Esp32

Post Reply

Who is online

Users browsing this forum: No registered users and 2 guests