Community Documentation

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?

https://v1engineeringinc.github.io/V1EngineeringInc-Docs/ - Ryan

https://docs.v1engineering.com - Ryan

1 Like

I’ve used readthedocs in the past.

Github part:

Rtd part:
https://v1pi.readthedocs.io/en/latest/

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

  1. check
  2. check
  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.

It is indeed a good idea to start with a wishlist (err. requirements gathering).

Here’s my take:

  • 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
 
1 Like

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.

https://www.growingwiththeweb.com/2016/07/enabling-pull-requests-on-github-wikis.html

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.” :stuck_out_tongue:

2 Likes

Something I’d like to see is a per-part page on the wiki. (a whole tree, actually):

 

  • V1 Engineering
    • MPCNC
    • LowRider
      • Hardware
      • Flat Parts
      • Printed Parts
        • Lower Za
        • ...

Lower Za

Lower Za

Description

This part yaddas with the fronombulator and interfaces with the decathotron to couple the flux matrix to the interocetor helix.

Associated Hardware

  • Metric
    • M5x65 (3x)
    • ...
  • Imperial
    • 5/16x1.5" (3x)
    • ...
Used in
  • Y plate Assembly

Backlinks:

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

4 Likes

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.

3 Likes

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?

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…

1 Like

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.

The dRonin project used jekyll to build their documentation and host it on github. Site: https://dronin.org/docs/ Repo: https://github.com/d-ronin/d-ronin.github.io

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.

 

1 Like

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.

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?

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.

Hexio has a wordpress export, https://hexo.io/docs/migration

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.

https://help.github.com/en/articles/adding-a-file-to-a-repository

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 Like

The “improve this page” at the top. Yes, that’s just what we need.

1 Like

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)