Community Documentation

They other way I believe, Not sure, but that would be cool as well.

What?! Github has stl preview? And diff too it appears. My days on TV may be numbered!

1 Like

Diff, no, how. Do you have a link? That is nuts

SHOOT!

Aside from content of the individual topics, it would be helpful to consolidate information from different pages into one page. For example, right now, Iā€™m looking for post processor information, I know that Iā€™ve seen it on one of the pages at the bottom. I know that Iā€™ll have to comb through 3 or more pages to find it. So at the end, it would be great to have everything consolidated into a rough heirarchy that might resemble something like:

  • Home
    • MPCNC
      • Hardware
        • Parts
          • Thingiverse links
          • Boards (with links to the store :)
            • Pinout Diagrams
            • Detail of polarity of the pins (I know I had to search around for this for the archim board)
        • BOM
      • Software
        • Firmware
        • CAM/Controllers
        • Post Processors
    • MP3DP
      • (sorry only have experience with the CNC at this time)
  • Shop
  • Forum
  • Contact
  • Login
Ā 

Ā 

2 Likes

I donā€™t see any reason why you couldnā€™t use the CC-NC license for your stl files in github. It might make sense to keep them in a different project than the docs anyway.

IDK about making two parts of one repo have different licenses. Iā€™ve never seen that. You can also look around on github for other licenses.

Firefox, as am example, owns trademarks on their logos, and their name. Then they release their software open source and free as in beer. They make money by putting things like the amazon search engine in. But you could copy their code, replace the logos and try to make your own money with it. Ice weasel, afaik, is just a recompile from source of their browser with a different name to remove the monetization. Someone could make a airbadger with banggoodā€™s search engine and if enough people used it, they could make money on it. If you did that with mpcnc, then someone could sell opcnc parts on ebay, but they would need their own images.

If you could find a way to keep your trademarks, and release the documentation open source. Just the documentation. That would be cool. Maybe the logos are links back to the images on your server?

Hereā€™s another interesting example. This is made with mkdocs and mkdocs-material. I think mkdocs is what readthedocs uses.

Example:
https://docs.keeb.io/iris-rev3-build-guide/

Mkdocs:
https://www.mkdocs.org/

Mkdocs-material:
https://squidfunk.github.io/mkdocs-material/

It looks like the static to wordpress is a bigger hurdle then I imagined. How bad would it be to have ~external~ instructions?

It could end up being docs.v1engineering.com or another subdomain. Seems fine to me. One downside is the links in the forums might not expand to do previews?

Just while Iā€™m thinking of it: if the parts and documentation are migrated to GitHub that would be a good time to choose more ā€œself-documentingā€ (or at least more consistent) names for the STL since there would be a clean break of both the docs and the files.

Ā 

For the LowRider we currently have:

  • cable_tie_insert
  • LR2 X Mount
  • X2 Plate
  • VacShoeFront
  • Lower Za
  • YZ Roller M
  • XZ
  • XZ Main
  • XZ_Side_Belt_Mirrored
So the complementary piece is sometimes "M", sometimes "b", sometimes "Mirrored". Sometimes there are underscores in file names, other times spaces, sometimes capitalized, sometimes not, and once with an LR2 prefix. The situation is hardly a disaster, of course, but if the project is handed an opportunity to start fresh I suggest we take it.

Also, that STL visual diff is super cool.

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/

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

2 Likes

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.ā€

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 Like

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ā€¦

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

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

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?

[attachment file=ā€œscreenshot-2019-09-19-1568917012.pngā€]

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

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.