Documentation Feedback : Contributor Onboarding Experience

[Prachi-Gupta2808]

Documentation Feedback

Hello @Ryan-Millard and @Krasner As promised, here's my feedback after going through the docs ("old"/current version) over the past couple of days and contributing.

What worked well

• The Getting Started guide (Docker setup, cloning, installing dependencies) was clear and easy to follow, especially with prior React/Docker experience.
• The codebase itself is well commented, which made it easier to understand once I was inside it.
• The useWasmWorker and wasmWorker.js reference pages were genuinely excellent, they helped me understand the WASM/JS memory model deeply.

Gaps I ran into

1. WASM build step missing from Getting Started
The Getting Started guide doesn't mention how to build the WASM module. I had to ask in #394 and was given:

emcmake cmake -B build-wasm .
cmake --build build-wasm

This should probably be added as a step in Getting Started, since without it packages/js/build-wasm doesn't exist and nothing works.

Krasner mentioned that PR #439 (introducing a Justfile) should address this by bundling setup commands like this into something simpler, e.g. just init-img2num. Linking it here so it's tracked alongside this feedback.

2. Reference docs describe an architecture that doesn't match the current codebase
Several reference pages (Vite Configuration, WASM Reference overview) describe a src/wasm/modules/{name} structure with npm run build-wasm / npm run build-wasm:debug scripts and auto-rebuild Vite plugins. However, the actual current codebase uses bindings/js + packages/js, built via CMake/Emscripten directly (emcmake cmake + cmake --build), not the structure described in these docs. This was confusing since I assumed these reference pages matched the current code.

3. Broken links in Editor page test docs
The Editor Tests reference page links to:

https://github.com/Ryan-Millard/Img2Num/blob/main/src/pages/Editor/Editor.test.jsx

but the actual path is under example-apps/react-js/src/pages/Editor/Editor.test.jsx, so these links 404.

4. wasmWorker.js docs don't mention Node.js support
After #433 adds worker_threads support for Node.js, (and you guys do the required changes) the wasmWorker.js reference page should probably be updated to document the dual environment behavior (browser Worker vs worker_threads, and how isNode.js is used to detect environment).

Question

I was also curious about the "Next" version of the docs what's the plan with it? Is it for an upcoming architecture redesign, or are you guys thinking of shifting to next.js, or is it something else?

Happy to help fix any of these, let me know which ones make sense to tackle first and your reviews if I am pointing out something wrong.

[Ryan-Millard]

Hi @Prachi-Gupta2808. Thank you for the input!

1. WASM build step missing from Getting Started The Getting Started guide doesn't mention how to build the WASM module. I had to ask in #394 and was given:

emcmake cmake -B build-wasm .
cmake --build build-wasm

This should probably be added as a step in Getting Started, since without it packages/js/build-wasm doesn't exist and nothing works.

Krasner mentioned that PR #439 (introducing a Justfile) should address this by bundling setup commands like this into something simpler, e.g. just init-img2num. Linking it here so it's tracked alongside this feedback.

Yes. #439 will implement something that will make it much easier to set up the project because it'll contain a command that sets it all up for the user. #303 mentions setting up Git hooks, which would be a good idea during that setup phase as well - the only problem is ensuring that the hooks remain usable regardless of the OS (I make my commits on Windows 11, but run the code in the Docker container).

2. Reference docs describe an architecture that doesn't match the current codebase Several reference pages (Vite Configuration, WASM Reference overview) describe a src/wasm/modules/{name} structure with npm run build-wasm / npm run build-wasm:debug scripts and auto-rebuild Vite plugins. However, the actual current codebase uses bindings/js + packages/js, built via CMake/Emscripten directly (emcmake cmake + cmake --build), not the structure described in these docs. This was confusing since I assumed these reference pages matched the current code.

That sounds a lot like something I may have forgotten to update when I did the #250 refactor. This project used to be just the React example app before I realized that it would be a good idea to make it available for other people who share similar problems to what I faced (most raster-to-SVG libraries don't have good support for natural images because they were created to improve blocky synthetic images - see here: Potrace examples, imagetracerjs example, other examples). Our library is basically the opposite of theirs: it doesn't handle synthetic images as well as theirs, but it beats most at maintaining important details (depending on how you configured it, of course).

We will definitely need to change the documentation to resolve those mistakes. @coderabbitai please create an issue for this point (2) to get the documentation fixed. There are broken links and outdated content.

3. Broken links in Editor page test docs The Editor Tests reference page links to:

https://github.com/Ryan-Millard/Img2Num/blob/main/src/pages/Editor/Editor.test.jsx

but the actual path is under example-apps/react-js/src/pages/Editor/Editor.test.jsx, so these links 404.

I think this ties into the point I made about #250 because example-apps/react-js/src used to be just src before that refactor (see the commit that came before it).

4. wasmWorker.js docs don't mention Node.js support After #433 adds worker_threads support for Node.js, (and you guys do the required changes) the wasmWorker.js reference page should probably be updated to document the dual environment behavior (browser Worker vs worker_threads, and how isNode.js is used to detect environment).

It will definitely need to be updated, but I'm not sure about the workers. I did mention that I'm considering removing them in #433 to make the library simpler and give more power to our users.

Question

I was also curious about the "Next" version of the docs what's the plan with it? Is it for an upcoming architecture redesign, or are you guys thinking of shifting to next.js, or is it something else?

Next is supposed to represent what is coming in the next release of the project, but I messed it up. I'm currently having a hard time trying to figure out how to properly version our docs because we have 4 libraries that are versioned independently, so we can't have just one version selector. I also haven't had time to experiment with swizzling and more advanced things because I've been focused on other important tasks.

• Docusaurus versioning docs
• Docusaurus multi-instance docs versioning

Basically, we need to remove the old version because we don't really want users to be looking there. Next is far better-structured than old is.

[Prachi-Gupta2808]

it would be a good idea to make it available for other people who share similar problems to what I faced (most raster-to-SVG libraries don't have good support for natural images because they were created to improve blocky synthetic images - see here: Potrace examples, imagetracerjs example, other examples)

After reading this, I would like to mention that we need to add this and more catchy stuff on our readme file to attract more contributors and people, I found what you guys are building interesting but reading these line in particular and seeing the examples made me feel so good about this project.

when I was looking for repos and projects to contribute in I get attracted by the read.me files which also adds why the project is needed.

If you guys can highlight more of similar stuff about the project and some of your ideas, I can help and update readme file.

[Ryan-Millard]

it would be a good idea to make it available for other people who share similar problems to what I faced (most raster-to-SVG libraries don't have good support for natural images because they were created to improve blocky synthetic images - see here: Potrace examples, imagetracerjs example, other examples)

After reading this, I would like to mention that we need to add this and more catchy stuff on our readme file to attract more contributors and people, I found what you guys are building interesting but reading these line in particular and seeing the examples made me feel so good about this project.

when I was looking for repos and projects to contribute in I get attracted by the read.me files which also adds why the project is needed.

If you guys can highlight more of similar stuff about the project and some of your ideas, I can help and update readme file.

I'd really like that kind of update. I want to get our first stable release going and have it proven that others can use it first because we'd likely be changing things far too often otherwise. The text about natural images could stay, though.

My plan is to have a page on our website dedicated to showcasing what the library can do and what happens when you change the arguments you pass to the functions.