September 13, 2019 at 6:03 am #113936
How can we contribute to the documentation?
Here are my ideal goals for this (Ryan please correct or add to these):
1) The output format needs to be readable, contain images/gifs/videos, be organized into sections and subsections and links to specific parts to paste in the forums.
2) Edits need to be approved by Ryan or trusted admins. Since all kinds of very new people will see it, there is a lot to consider.
3) Edits need to be easy, ideally, not requiring installing git on your computer. Many of the users know how to do that, but the most eloquent ones may not :).
4) It needs to be easy to locate or integrate from v1engineering.com so users will actually find it.
So what does that system look like?September 13, 2019 at 6:10 am #113937
I’ve used readthedocs in the past.
I used restructured text (.rst) and the output came out ok.
Changes need to be made on the github side. So someone can fork it, make edits, and submit a pr. I think you can edit a file in github’s web ui. I’m not sure the preview will match (especially the links).
3) sort of…
4) sort of…
So there would be a single repo, like v1_instructions and a readthedocs account would be set up to build them and host the output.September 13, 2019 at 6:20 am #113942
It is indeed a good idea to start with a wishlist (err. requirements gathering).
Here’s my take:
September 13, 2019 at 6:24 am #113946
- Guided contribution process (think pull requests)
- Availability of WYSIWYG editor (so less technical users don’t have to write wiki format directly)
- Automated process e.g. no manual sync to update docs after PR is approved
- Must support images
- Format must have a WordPress plugin so the docs can appear on v1engineering.com
Reposting the github wiki article. This seems to be a fairly popular method. I’ve seen a variation all over the place. I need to do some research to see how it would work with WordPress.September 13, 2019 at 7:11 am #113968
I have a few comments on documentation in general, including some commentary on the Herculean job Ryan has been doing so far.
1: Consistency. There needs to be a format and guidelines for documentation. As a counter-example, look at the MPCNC and MP3DP project pages. I realize that they are in slightly different stages of development, but one is well formatted and laid out, the other is almost stream of consciousness by comparison. Again, not trying to knock Ryan, he’s doing a massive amount of work on his own, and I’m sure it gets overwhelming at times.
2: Duplication of Data. Don’t be afraid of it! But make sure you’re aware of when it happens, so you can change it consistently when needed. Nothing annoyed me more than dealing with IBM AS/400 manuals back in The Day(tm). They absolutely refused to print any useful piece of data more than once in a bookshelf-sized set of manuals. So it boiled down to at least two-thirds of the printed content was references to somewhere else (which was sometimes another reference). It’s not so bad with hypertext, since those references can be links, but if it makes sense to present the same information in different ways, do it.
3: Validity of Data. Link hygiene. Making sure that all your references are still valid. Absolutely sucky job, and one that I’m sure nobody likes. But I also know that nothing screams “abandoned project” like a page full of links to dead or missing sites, or references to out-of-date tools or techniques (e.g., a web design page that has a section devoted to the blink tag).
I’m sure these are reasonably obvious things, but they are also ripe for “everyone assumed someone would do it, so nobody did it”.
Also, this is not a offer to volunteer. Trust me, you don’t want me actually writing documentation, or in any sort of position of responsibility. To paraphrase the Dread Pirate Roberts: “Well done, good job, I’ll most likely ghost you in the morning.” 😛September 13, 2019 at 7:35 am #113977
Something I’d like to see is a per-part page on the wiki. (a whole tree, actually):
- V1 Engineering
- Flat Parts
- Printed Parts
- Lower Za
This part yaddas with the fronombulator and interfaces with the decathotron to couple the flux matrix to the interocetor helix.
- M5x65 (3x)
- 5/16×1.5″ (3x)
- Y plate Assembly
- Parts list
- Printed Parts
- Assembly: Y-plate
The purpose of this is to allow every reference to that part (And I would suggest that part name could probably stand to be renamed?) to be linked to this page, and hovering over the link can provide a picture of the part and a brief description (similar to how Wikipedia and others provide tooltips with previews of internal links) so people working their way through the documentation will know exactly what they are supposed to be looking at.
I think that would be immensely helpful, but having to maintain that by hand rather than being able to generate all of those pages from a template and a source spreadsheet or csv would be a bit of a nightmare.
September 13, 2019 at 8:28 am #113985
- This reply was modified 1 month ago by frosty.
First of all I like to say that I think this is an awesome way to give something back to Ryan, because we as the (maybe unexperienced) user and builder have a different take on the manual/documentation and the problems we faced.September 13, 2019 at 11:01 am #114008
What about something as simple as a google doc. People can cut and paste to make minor edits or cut and paste a template page to keep with a standard. The the people allowed to make changes can just cut and paste them in.
I would prefer it to have a history like github where your contributions are written into its history. I like to think I can show someone I have actual code in Marlin. Brings me joy.
Master ZenJ, your Sandify page is easy to edit?September 13, 2019 at 11:23 am #114014
From an end user perspective, dozuki guides are great. I remember seeing them on iFixit and being very impressed at how clear they allowed things to be.September 13, 2019 at 11:38 am #114016
Looks like Dozuki is commercial these days, although they do have a CC/OS plan that may be free. The only issue is that anything published needs to be CC-SA. Now, you might get away with putting up the documentation as CC-SA, and leaving the STLs on Thingiverse as CC-SA-NC. But that’s just me musing on a Friday afternoon…September 13, 2019 at 12:07 pm #114024
Dozuki is great…but not cheap and the terms on their open plan are a bit iffy (like allowing them to add advertising you can’t control.)
Not a fan of google docs for this kind of thing, my 1st printer had that kind of documentation and it proved to be a pain to integrate updates. Plus it’s harder to format well and just doesn’t seem as polished.
It’s not super great for inexperienced people to submit updates to though. It’s all done in markdown and you have to be able to pull and submit PR’s to get your changes accepted. And Jekyll proved to be a bit tricky to get styled well in a few ways.
There are a number of similar options though they all require some technical experience to setup and work with.
There may be a wiki option that allows an approval process similar to PR’s….but I’m not overly familiar with wiki’s.September 13, 2019 at 12:31 pm #114028
There are a number of static site generators like Jekyll that can be used. I use Hexo (http://hexo.io) for my personal website. And you’re right, it can be a pain to update (aside from the motivation to actually update it). On the flip side, if prepped carefully, you can create templates for most use cases, and the content creators just have to learn markdown and just enough YAML to
be dangerousget their docs published. And not using Jekyll is problematic with github as Jekyll is supported by GitHub Pages, but other generators aren’t. You’d have to tie in some sort of CI workflow.September 13, 2019 at 12:42 pm #114032
Master ZenJ, your Sandify page is easy to edit?
I find it easy, but I’m a software engineer.
Editing .rst or .md files is pretty easy, but you need to have a way to see how it will be compiled into the webpage before you’re done with it. Think of something like a thingiverse page, where you can edit the text and add in headers, bold, italics, pictures, links, but before you publish, you look at the “preview”. That’s what we need, but then the submission ends up being a PR request, and the output looks a lot less homely than thingiverse.
I think we can do 90% or more of that with github. The original process linked to github/github wiki is good, but I have a little trouble navigating github wikis. The readthedocs front end might help.
Maybe someone could try it with the v1pi project? You can fork it, see if you can edit it in the browser (I think github will let you do that) and then the key part, is there a way to PR that, and see the output in readthedocs?September 14, 2019 at 10:32 am #114113
I just tried editing the second posts links. This is actually extremely easy and almost the exact same as doing description in Thingiverse.
I can edit it in the browser, following what is already there it is pretty easy to keep the “style” then hit pull request. I did not see a way to add a file though (from the browser). It says uploads not allowed.
You can see a preview on the same page before submitting the PR. I like it, Nothing to install.
Style – Not sure how far we can go with the formatting.
Adding a file/picture –
Bringing it to the site – or is that even an issue? Should this be stand alone, why / why not?
Sorry, I did look at the other links but I don’t understand what they are. Are they options for the framework instead of Read The Docs? I couldn’t find examples.
This is already pretty promising and could be very awesome for sooooo many pages. People can make there own and submit them, think a new page for every laser (with minimal tweaks, plasma cutters, clay extruders, very specific branches and things. Kinda blowing my mind on how much this could help.September 14, 2019 at 10:34 am #114114September 14, 2019 at 10:42 am #114115
Starting to understand. Hexo.io and Jekyll do seem good. Jekyll’s doc page even have a link at the top that say “improve this doc, EXACTLY! Just like that.September 14, 2019 at 12:41 pm #114126
I did not see a way to add a file though (from the browser). It says uploads not allowed.
Maybe I need to change some setting or try it myself.
I like the idea of using github as a back end. I can see this being a good start for lots of improvements. Might you even consider hosting the files there instead of or additionally to TV? Their stl preview is pretty awesome.
It’s also possible that changes could be a collaboration between an author and someone more technical to help them fit it in. So if, for example, someone wanted to add in a laser part page, they could, but if they couldn’t figure out how to get it linked together, it would be just a few minutes from someone more familiar with it.
If you chose something like hexo.io, and the files were markdown held in github, you’d be able to edit them in github, and see a rich preview, but maybe not exactly the same as the output from hexo.io. Then you would either manually run a script to build your v1engineering pages, or have a CI bot do that after a merge to ‘master’ or something. I’m assuming jekyl would work the same way. Hopefully, things like images and links work the same in github as they do in the front end, so that when you’re editing for a PR, you can be sure they are right without having to run hexo.io.
I’m not 100% on this, but I think readthedocs only posts to readthedocs.org, is that right? I don’t know at this point how to differentiate between the different options. Anything that supports markdown is probably going to be ok.
Ryan, do you have a license in mind? You’d be posting your logos and pictures of your parts, from CAD or from your workshop, but presumably so would the contributors. Before you go open this box, you should get this right. I wouldn’t want images from this repo ending up in ebay descriptions, but If there was something like a tutorial on a laser that someone submitted, it would make sense for them to also use that for another project if they felt like it.
1 user thanked author for this post.September 14, 2019 at 12:52 pm #114129September 14, 2019 at 1:01 pm #114133September 14, 2019 at 1:08 pm #114137
Yeah it looks like the upload part is a setting on your end, I can follow those steps and it says no. No big deal, it is possible that is all that matters.
Look I hope no one gets insane about this comment but when I keep asking how does an open source business work, this is what I was asking. This is how people can help and we don’t end up with parts and instructions all over the place. I would not get stuck making instructions for every cool thing that comes out. Or a totally fragmented design. Like Marlin there are like 8 people with permission to pull and edit but for the most part thinkyhead handles it and drives the boat. If he goes away there are 7 left. This makes it so people CAN help if they want. This feels like a huge step in the right direction, the money issues are later but this is a huge eye opening experience. I see how it could/might/maybe work now. Lots of hurdles to overcome but I appreciate you all stepping up and helping me to understand. This could also really help with server issues.
So yes license is going to be a huge issue. I am not sure. Suggestions welcome. Probably best to stay away from stl’s for now but this could make sense. I was trying to find that thingiverse alternative you found a few weeks back heffe. They might have some license options I have not seen. I swear it was wikifactory or something like that? They were emailing me every few days and nothing now that I want one.
If we can find a way to differentiate the options that would be cool. If not I guess I just watch videos on them and see which one seems easier and not very limiting. Still not sure if this site getting the docs is a requirement if it looks good (like the shop being totally separate, not idea but works great)September 14, 2019 at 1:09 pm #114138
This is to go from your current docs into hexo.io?
They other way I believe, Not sure, but that would be cool as well.September 14, 2019 at 1:17 pm #114141
What?! Github has stl preview? And diff too it appears. My days on TV may be numbered!September 14, 2019 at 1:20 pm #114142
Diff, no, how. Do you have a link? That is nutsSeptember 14, 2019 at 1:24 pm #114143September 14, 2019 at 1:36 pm #114144
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:
September 14, 2019 at 1:38 pm #114145
- 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)
- Post Processors
- (sorry only have experience with the CNC at this time)
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?September 14, 2019 at 3:31 pm #114168September 14, 2019 at 7:41 pm #114188
It looks like the static to wordpress is a bigger hurdle then I imagined. How bad would it be to have ~external~ instructions?September 14, 2019 at 8:44 pm #114197
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?September 14, 2019 at 9:42 pm #114198
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:
- LR2 X Mount
- X2 Plate
- Lower Za
- YZ Roller M
- XZ Main
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.
You must be logged in to reply to this topic.