Yeah, I think this is critical. What I was proposing was to edit the files in github, and then have people submit pull requests. Even if Ryan still does the final button clicking to merge in changes, it would be 9x-99x easier for him. He could be completely out of the loop if he just added some admins using github credentials. You can get pretty granular there, like adding 10 people to the github, but master can only be edited by Ryan, or whatever.
The first thing to do would be to take some screenshots and write up how to edit the documentation. It would be a good rough draft of the process. It would end up sort of like a wiki, but with the added step of having all changes have to be approved. Also, issues could be added by people who couldnāt be bothered to change it (like if someone found out socket cap screws donāt work, they could add an issue, even if they didnāt want to edit the documentation).
Hoping to get on this soon. I have a meeting today in 10 minutes, then orders, pickup the first batch of prepackaged hardware tomorrowā¦Then I hope I will have some time to get this going, or try it out at least. The prepackaged hardware could help me turn the corner and get back to the fun stuff!!
Regarding the copyright. Unless you have a better idea, I think itās low risk to just make any critical V1 images link back to your site, so they stay under your copyright here, and just put the text up with an open source license. Some of the images could be hosted on github. For example if someone took a picture on their own to clarify a step. Of course, you can be as generous as youād like with your images, Ryan, if you want to host all the instructions in github.
I would avoid GPL2 or GPL3, because they can be very open source, requiring you to release any future edits. I use MIT on my projects, usually, because if someone like you wanted to do something like sell an SD card with the v1pi image on it, and it was GPL2, then youād also have to release any modifications to the SDCard under GPL2.
Why read the docs? I see so many options and not any huge differencesā¦from my noob perspective at least. Looking for any reason to use one over the other. Jekyll seems to have the largest user base?
Either will work. A few projects I follow use RTD or RTD clones. The cooked in style is easy to read and lends itself to documentation, with a static menu on the left and content on the right. Iām sure you could find/build a similar theme for Jekyll (or any other static site builder). It looks like the primary benefits are effectively CI for your docs, multiple formats, and free hosting. But thatās what Iām seeing, and I may be missing more (or missing some downsides).
License decision is important to get right. Changing the license of a community project after a fact is hard. Everybody who contributes to the docs retains copyright for their part of the docs so re-licensing involves getting explicit permission from everybody. Generally itās possible to go from more permissive to more restrictive by switching the license for new work which will put the collection as a whole under a new license given the two licenses are ācompatibleā. Itās very hard to go the other way around.
This is how community contributions work. The license is something every individual contributor will have to consider before they pour their heart and soul into it.
Now when it comes to a specific license, I suggest a simple CC-BY or CC-BY-SA for the docs and take out a trademark to police the usage of the name MPCNC to protect from bad actors.
NC is problematic for many practical uses. Letās say there is a local makerspace with a bunch of MPCNCs. Do we want them to be able to hire a guy to train new members in how to use the machines and charge a fee for a course? If so then NC is a problem because it forbids such usage. What if they want to assemble a handbook for members that has local customization details in it? They charge membership fees so NC is again problematic. Do we want people to avoid official docs and come up with custom crappy ones to work around the license?
Another issue with NC is that the moment there are multiple contributors to the docs, every single one of them has to agree to monetizing the docs by V1Engineering. So Ryan will not be able to sell a printed version of the docs in his shop or even include a copy with a kit unless everybody who has contributed to the printed version of the docs explicitly signs a contributors agreement granting him a separate right to do so. If this is not done, it only takes one person to make a stink and the situation can become really unpleasant.
Whatever is chosen, a custom license is the worst unless a lot of money is spent on good IP lawyers for drafting it.
Only if you want the docs to proliferate in places where SA would block it. E.g. if some1 wants to print part of the manual in a book about Hobby CNC-s and can not / will not release the rest of the book under CC.
EDIT: In a nutshell SA licenses are used if the primary objective is to keep derivatives free, SA is not used if the primary objective is to get as wide of an adoption as possible.
Ugggggg licensing suckkkkks. Without the SA canāt you just fork and apply any license you want meaning almost useless without it in this case? If someone wants to publish under a different license canāt they ask and be granted permission?
As long as you stipulate that contributors to the documentation give licence to distribute w/out restriction, Ryan Iād free to grant permission on a per-case basis if someone asked.
Yeah, I agree. This has been a constant nuisance for my entire career with a healthy dose of corporate legal teams and their often unreasonable fears in the mix :S
You canāt fork and re-license unless you have explicit permission from each copyright owner. With a community project itās basically the entire community. Without SA people still can not apply new license to the material however they can add their own material under a more restrictive license and then distribute (sell) the resulting combination as a whole under more restrictive terms.
EDIT: SA prevents such action: You canāt combine SA material with material that has a more restrictive license (e.g. fully closed aka āall rights reservedā).
Ok so the final fight is between RTD and Jekyll? Or is GitHub wiki still in the ring?
/me grabs the popcorn.
Joking aside, Ryan once you have winnowed down the list to your linking, do you need some IT guy (including yours truly) to take a stab at wordpress sync? I think I have some wordpress site I can use as a sandbox somewhere, not sure which version itās running though.
I reread this whole thread. and looked at the links again. MK docs is the base and RTD is just a theme? Either way it looks good, I think a walk through on editing would be easy, a link to a Markdown cheatsheet, or people could just submit changes to a thread and someone could submit them I suppose. a million times better than what we have now, no matter what.
I say cc-by-sa for now. A few choice images will be linked form the site. I do have a pending trademark, it takes forever and the first one got denied for a stupid tiny minor issueā¦grrrr. I had to resubmit and pay again, they called me but would not let me just pay again and make the one change.
I have tried a few times to get the name I wanted but have received no reply so I will try to get RTD going with the other github account.
I agree that Markdown should be easy-enough to use.
Last time I checked, GitHub even made it very easy to edit Markdown files. You can hit edit when viewing a file in a repository and it even creates an automatic fork if you canāt write to the repository. From there one can easily open a pull request with the changes. I think PRs are more sustainable than forum posts that still require a bunch of manual actions to apply/merge.
EDIT: AFAIK readthedocs is both a theme and a hosting service if you canāt or donāt want to run doc site yourself.
I donāt know anything about the ābehind-the-scenesā of any of the options. Iām not a developer. As a mere user of various projects (typically network management/monitoring related tools) and trying to read documentation, I find RTD to be very clean, logical, efficient, and intuitive. github, not so much. I think github could also reinforce the misconception that the MPCNC/LowRider2/etc are open source.
Wait, NC means you canāt use the MPCNC in a classroom setting if you charge for the classes? Thatās different from what I understood. NC means you canāt build them for resale or sell kits and such, but you can use them to make money, including using them in a classroom settingā¦
My stipulation. Using cc I can add more relaxed stipulations not more restrictive. So I have clarified I am only concerned with my parts and files, using them to make money in any way is fair game.