Here are my ideal goals for this (Ryan please correct or add to these):
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.
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.
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 :).
It needs to be easy to locate or integrate from v1engineering.com so users will actually find it.
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).
check
check
sort ofâŚ
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.
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.
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â˘. 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.â
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.
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.
For me one of the best documentation systems right now is dozuki. It is used by e3d, prusa and many others, but Iâm not sure if it is free anymore.
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.
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.
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âŚ
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.
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 dangerous get 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.
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?
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.
Some concerns.
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.
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.
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.
This is to go from your current docs into hexo.io? I wonder what format they would end up in. If they would still be easily editable. It might be easier to go through and basically remake them from the same text, and images.
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)
