Community Documentation

New Home Forum Software / Firmware Development Community Documentation

This topic contains 158 replies, has 15 voices, and was last updated by  Jeffeb3 4 days, 14 hours ago.

Viewing 30 posts - 31 through 60 (of 159 total)
  • Author
    Posts
  • #114523

    Ryan
    Keymaster

    Ahhhhhh I choked/panicked. I was trying to get a feel for github.io and maybe jeykll and I need to choose a license. Crap. I can’t do anything until this decision is made.

    From github, https://choosealicense.com/non-software/

    #114543

    frosty
    Participant

    What is lacking in the same CC-BY-NC-SA-BBQ license you use for the STLs?

    1 user thanked author for this post.
    #114546

    frosty
    Participant

    You could probably roll-your-own license for documentation too.

    “This document is Copyrighted by V1 Engineering and made available to the public free of charge. You are free to download, duplicate, and distribute unmodified versions of this documentation for non-commercial purposes provided this copywright notice and the list of contributors is retained unaltered. If you wish to published a modified version of some/all of this documentation you grant a world-wide, non-exclusive, royalty-free and perpetual right to V1Engineering to use, copy, modify, communicate and make available to the public all modifications. In consideration of your contributions your name and contact information will be added (if desired) to the list of contributors.”

    #114547

    K Cummins
    Participant

    Keep the projects (models/documents) separate, and remember that you can change the license at any time. CC-SA-NC should be more than sufficient for the documentation. Even if you aren’t monetizing it, it’ll prevent some yahoo from chucking it all into a poorly-formatted PDF and uploading it to Amazon… Like we need more poorly thought-out vanity publishing projects and/or money grabs. (Except Chuck Tingle, the world needs more Chuck Tingle titles [not that I’ve ever read his books, but his titles are killer])

    1 user thanked author for this post.
    #114556

    Bill
    Participant

    I think I’m in favor of using the GitHub wiki and linking from the website to the documentation. Design the wiki so there’s always a link back to the website available and use something like what frosty and Tealfixie suggested as the framework. Leave the onsite docs showing the basics and drill into details on the wiki. Potentially encourage some of our better skilled users to do very short video builds on each part or assembly…

    #114557

    Jeffeb3
    Participant

    IDK, I’ve never seen a github wiki have good documentation. It’s still very noisy with all the other github stuff going on.

    #114561

    Ryan
    Keymaster

    Links to a good example maybe bill?

    We are getting close and it really is a relief to me. I had no idea how big of a burden the instructions were to me until we started this conversation…and now the firmware. Things have just progressively gotten more complicated and I had not noticed how much work everything takes at this point (1 firmware…now 12,).

    #114740

    Bill
    Participant

    Maybe the HTML5 Boilerplate Wiki or Markdown Cheatsheet on github? I’m not advocating their wiki over others, it just that the wiki concept can be so useful, and you already have a V1 presence there. I haven’t checked but I imagine you can define a custom header or footer that will be included in each of your pages, and that can act as the link back to your website. Another option would be to force the link from the website to the documentation to open in a new tab/window so the site is still available while you browse the docs?

    #114745

    Jeffeb3
    Participant

    screenshot-2019-09-19-1568917012

    This is what that looks like to me. There’s a huge banner, links to marketplace, my other projects, the code, etc. It’s really hard to tell where github ends and the wiki begins.

    Compare that to something like this: https://nlopt.readthedocs.io/en/latest/ . All the info is related to the project, there’s a ton of info here with a TOC on the left pointing out where you are in the docs. It seems much easier to follow rtd step-by-step than a github wiki.

    The wiki concept on it’s own won’t really work, right? Because people will either have free reign to just make changes, or they will not be able to change anything (I can’t make edits to the markdown cheatsheet). By forcing the edits to be through PRs, it will allow anyone to add their $0.02, have a public debate about it (which might be as simple as, “cool”) and then merge it smoothly into git.

    I hope I’m not being too frank about it. This is just my opinion. It’s totally possible I missed the point of a wiki :).

    #115137

    Bill
    Participant

    Hmm, all I see is the tabs line and the wiki content. Must be my ad blocker doesn’t show the rest. The reason I see for using a wiki is that Ryan doesn’t have to do everything. That has the potential to be a disadvantage since if Ryan doesn’t have to do everything it means someone else can screw it up. If there were a connection between the forum software’s back end and the wiki you could set things up such that only forum members have the ability to edit and with the ability to undo any edits, or perhaps have an administrator who approves edits that could be minimized.

    #115138

    Jeffeb3
    Participant

    The reason I see for using a wiki is that Ryan doesn’t have to do everything. That has the potential to be a disadvantage since if Ryan doesn’t have to do everything it means someone else can screw it up. If there were a connection between the forum software’s back end and the wiki you could set things up such that only forum members have the ability to edit and with the ability to undo any edits, or perhaps have an administrator who approves edits that could be minimized.

    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).

    #115139

    Ryan
    Keymaster

    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!!

    #115141

    Jeffeb3
    Participant

    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.

    #115152

    Heath
    Participant

    I agree with Jeffeb3 about the github wiki and would also prefer readthedocs.io.

    #115153

    Ryan
    Keymaster

    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?

    #115164

    K Cummins
    Participant

    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).

    #115173

    Ryan
    Keymaster

    Sweet, I like how Sandify looks and I understand how to edit it so I will have another look.

    #115181

    Anttix
    Participant

    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.

    #115183

    Ryan
    Keymaster

    I think cc-by-sa is comfortable for now. Is there any reason any of you see not to do it SA? I am looking through it on github now.

    1 user thanked author for this post.
    #115187

    Anttix
    Participant

    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.

    • This reply was modified 3 weeks, 5 days ago by  Anttix.
    #115190

    Ryan
    Keymaster

    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?

    #115191

    frosty
    Participant

    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.

    #115193

    Ryan
    Keymaster

    Dozuki is out, 50k page view limitation.

    Readthedocs supports PDF output and several people have asked to make it printable for shop use. Big plus.

    #115194

    Anttix
    Participant

    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?

    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”).

    • This reply was modified 3 weeks, 5 days ago by  Anttix.
    1 user thanked author for this post.
    #115198

    Anttix
    Participant

    Dozuki is out, 50k page view limitation.

    Readthedocs supports PDF output and several people have asked to make it printable for shop use. Big plus.

    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.

    #115199

    Ryan
    Keymaster

    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.

     

    1 user thanked author for this post.
    #115202

    Anttix
    Participant

    …  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 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.

    • This reply was modified 3 weeks, 5 days ago by  Anttix.
    #115214

    Heath
    Participant

    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.

    #115215

    Bill
    Participant

    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.

    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…

    1 user thanked author for this post.
    #115218

    Ryan
    Keymaster

    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.

Viewing 30 posts - 31 through 60 (of 159 total)

You must be logged in to reply to this topic.