Proposal: Assembly Manuals' Source - Move to Online for PRs (and generate the PDFs from there)
eduncan911 opened this issue · 4 comments
owners: apologies if this isn't the correct place. i can't seem to find the source of all of the assembly guides for all revisions. Just the PDFs here in this repo, and other repos.
Hello! The assembly manuals are awesome. Love the font, scheme, clearness, etc.
As I have purchased/sourced my parts for my 2.4 build, and starting to dig deep into Voron User mods, many many live streams of assembly (Tom, Nero 3dp, etc), and reading 1000s of chats, there seems to be a common theme that I haven't seen addressed yet. I can sum it up by repeating what I saw Nero 3DP enter into the chat multiple times over Tom's live streams of his 8 part series (oh yeah, I watched all 24 hours of it!!), along with other dev members/community members...
The manual needs to be updated.
(and) There's a running list.
Therefore, I would like to propose a different approach to these Assembly Manuals:
Place the source of the manuals online, and generate them from source (e.g. LaTeX) to iterate on them much faster. Also, tracking changes and allowing members to submit PRs in a central place.
I know the chaos this sounds like: opening up the precious documents to possibly 1000s of people thinking this or that needs to be changed. But, hear me out...
- I have had to start my own "things that need to be updated" list, order extra parts because X said Y in the live streams and not sure if I need to do that or not, because I can't find that "There's a running list" online anywhere.
- Having the "running list" online would be a great place for new builders to come in and say, "Ah, I should follow this Page 48 in the updated list and not the guide."
- Community members would see/experience issues with the assembly manuals, and propose the changes in a central place.
That last one is key: a central place to expose the current source of the assembly manuals, along with upcoming changes to those manuals.
It would help iterate the manual revisions much faster. Merge PR into master/main, manual gets rebuilt, pushed out to the appropriate repo automatically - daily.
If that "running list" are the Issues in this repo, then it looks like we are missing the online source piece. And it would default to someone still having to read the issue, verify the change, confirm it works, update the docs (wait for other changes), and then release a new one.
I have no idea what the source of the current manuals are. They could be Word Docs for all I know. lol
But, I do have experience with programmable methods of PDFs using LaTeX and templating, which really can automate this process with simple Markdown or whatever format you guys want to use to generate documentation from a common LaTeX template, font, color, etc.
This also offers a clean way to host PDF source files online in a github repo, for others to follow, open PRs, and make changes - even having a github action to generate a Preview of that PDF within the PR to confirmation.
If you would like someone to work on this, even a POC, let me know and I can whip something up based on the current manuals.
Let me try to address your different points.
- The current assembly guides are in Adobe InDesign. Unfortunately they do not support collaborative editing very well and there is no desire at the moment to invest in the work to migrate to another platform.
- Fast revs are not seen as being that much of a benefit as many people download the PDF and work from their local copy.
- Even though Nero is on the development team most of the views expressed that diverge from the Voron spec are his own. The spec was chosen by a group of folks examining a number of aspects.
- The issues on here are not a running list of incomplete revisions.
- If you or anyone else has changes they think should be made, please feel free to submit an issue here with the changes you think need to be made. Include screenshots or other images as needed.
Thank you for the perfect succinct list. Could not have itemized it better. :)
Let me reply to one point:
there is no desire at the moment to invest in the work to migrate to another platform
That's why this issue was opened, to start those discussions of moving to another platform to generate the docs that has good collaboration features (e.g. GitHub). All the while producing exactly the same quality document, fonts, layout, and so on in the end.
Is there a way to get this discussion in front of the "group of folks"?
I would be happy to put forward a POC for consideration.
You may not see it, but be assure that the "group of folks" sees these issues and reads them.
Here is my suggestion for you. It is a path already taken as it is where docs.vorondesign came from.
- Finish your Voron and get a serial.
- Build what you think the documentation would look like and publish it, preferably on a platform Voron already uses (e.g. GitHub).
- Bring it back up again and show us what you've built.