Community Documentation

P.S. There is a support link at the top of the github and a link to buy Heffe a beer or 12 up there!

I did a few pages today. The MPCNC Assembly ones were pretty short. The LR and MP3DP were way longer.

I am just so darn excited to get this off the ground. Since this came up, I’ve been wanting to write some new pages. Especially when I’m writing something long in the forums.

I have to say, I didn’t really appreciate the size of this documentation. Even thinking of the images. I copy/pasted the locations of probably 100 images. But that’s nothing compared to the work of setting up the scene, doing some kind of photography stuff (I’m no photographer), image editing and then uploading those. Same with the tables and text. I spent probably 20-30 mins today making the parts lists for the MP3DP, but all I was doing was copying the content. I didn’t have to go find the links or compose brief, informative descriptions.

So, hats off to you Ryan. This stuff really is a lot of work, and if nothing else, I hope this new system is easier for you. Better than that is if we get some people chipping in and making either good suggestions, high level designs, or even fixing typos. Maybe someday we’ll get someone in here who has some experience as a technical writer and they can really put a shine on it.

1 Like

Next steps.

  1. The switch. There are big warnings at the top of each page, saying that this is beta docs. We need to remove that warning, and Ryan needs to do the hard work of somehow linking to that other doc from here. What can I/we do to help? What is your schedule like to be able to do that? Do you want to clear out the Home menu and just make a Docs link at the top that goes to the mkdocs? Is there any content we are missing? Then you can put it on the front page.

  2. Editing for consistency. There should be a mind to consistency, at least through the set up for one machine, but ideally between the machines. Things like the way the step’s text and images are combined. Is there a consistent use of the various markdown tools? Does this interest anybody?

  3. Overall Design - I have been thinking that the documentation really has several purposes:

a) Walkthrough guide to setting up the machine, with facets for assembly, electronics, firmware, tools, software, etc. This is mostly what we have. But focusing on a walkthrough will show how much we are missing.
b) Reference. Things like the dual endstop page are more about putting good information in one place.
c) Tutorials/Teaching. I think some of what we have falls into this category. The mirror laser engraving page, for example. Stuff that isn’t as in depth as a reference, but has more detail to drag you through the content so some of it will stick. I’d like to write some stuff here for things we talk about a lot.
d) Troubleshooting. “My LCD doesn’t work”, “It’s not moving the right distance”, “It’s skipping steps”, “My head hurts”.

I think making some top-level spaces that follow this would let us really focus on a task for each page. We can always link around, like if there is a reference on screw sizes, we can link that in the assembly pages. Or if there is a tutorial on crimping, we can link to that from the electronics.

Then we should really focus on streamlining the walkthroughs. The walkthrough for an MPCNC is hard, especially towards the end, because you might have a rambo, mini-rambo, grbl, etc, and you might be heading towards milling, lasers, printer, etc. I think we should really have a strong “current” towards a nominal build, and have good, obvious, deviations for different variations. I really like the fork in the process that Dui showed, except I think we need to start with the design, based on what you want to do with the machine, and then get into the nominal build, and then split again for the different tools for 3D printing or milling.

When we have a place for all these things, I think it would be easier to take an hour, or even 15 minutes, and contribute somewhere.

  1. For switching my assumption is, first will be a main page post and and FB group post ( already gave them a heads up so I could see how it handles some traffic), this step is Soon. Makes sure some people see and use it. Then Ditch the warnings. Then I can start to switch the links in the main menu once we have finalized some sort of structure (point 3), then start to find and switch them thought the site. I can leave everything on the site but then add warnings here that they are potentially outdated, but available for old links and stuff.
So for step one, main page and FB post, work on a structure (point 3) so I do not have to change the site links multiple times. Right?
  1. editing consistency- Secondary but important. Find a page to use as a model and stick with it. Now that it is all there constancy is pretty easy. I hope people can help with this easily.

  2. overall structure- Yeah. I thought I would have more time to think about this part. A)(walkthrough) could either be a single page with a list of links in order, branched off for different uses? Or Keep things in order and each section ends with a choose your own adventure style link at the end (harder to maintain). Probably a hybrid, of the two since mkdocs already has next links built in.

we might be better off copying some pages to each machine initially even if they are the same (eg. repetier host), then if in needs to be specified it can. If we can get the main menu as small as possible and each category clear I would be really happy. So a category might be

MP3DP>

Intro, overview

Control options/ links to v1pi, repetier, grbl preferably with basic testing options for each

parts (?)

Assembly

Control options (better down here)?

Specific use cases page with link to stuff like printing/laser/chocolate

troubleshooting for this machine

b) (reference)linked in with (a) but probably lives with© in the menu? I think a dumping ground topic after the machines, these pages would be linked from several places so order here is probably not as important. Plasma, laser, concrete filled tubes, CAM, whatever. Remember it does not need to be the entire site, but can be.

c)In with (b)?

d)maybe best to have a troubleshooting page at the end of each machine linked to the actual pages in (b &c)

I am getting a feel for the overall flow, not sure yet. I can break out the notepad and do some quick brainstorming.

How about we use this as a note pad?

Okay peeps, looking like we hit another milestone.

https://docs.v1engineering.com/

New main menu/layout. This is setup with the first time builder in mind. Build my machine, Control my machine, then use my machine, learn some more advanced topics.

I hope to add a troubleshooting flowchart, list, table whatever for each machine. Typically it would be in order of a new builders perspective, so things like it is not 90 degrees to be above, did you check your pulleys?

Most of us will be in “use” and “Learn”.

Use, will hopefully fit the “how to” question. How to use a laser, plasma, drag knife. Pages that result in “something”. I hope to add another menu in use for “create”, make a dxf in inkscape, use CAD, as in how to Create a thing or design. Troubleshoot might need to get moved to Learn, but I expect this to be full of super simple pages with as many pictures as possible, eg, how to reverse a stepper. Things we can link to from the forums.

Learn should fit more of the nitty gritty firmware edits, gcode commands, work offsets, stuff that takes some deeper interest and desire to figure something out. Pages that make using it easier or more custom, things you would not expect a new user to even know exists or maybe should never really need to make basic projects.

So, Brutal honesty, take a look, offer suggestions, make edits, go hog wild.

I will slowly, ever so slowly, be changing the site links over as this progresses. I hope to have a main page post about this soon to bring more attention.

Again, Jeffeb3, a million thanks for your hard work, lessons, and patience.

3 Likes

So I have developed a very detailed set of instructions for milling metals with the MPCNC. I think it could stand as it’s own in the advance section of the engineering docs. I basically read everything I could find relevant to milling with a router based CNC and then spit it out in my own words, most importantly, as it relates the the MPCNC. It seems correct enough, but it does need at least some proofreading. How do I initiate this process?

3 Likes

What format is it in? How comfortable are you with markdown? What about git?

Ryan or I can help get a bigger doc like that converted to git and submitted as a PR. If you wanted to do it yourself, you would fork the repo, add the page, add the content, and then add it to the index.

But let’s do what we are best at. I don’t mind formatting and submitting it for you.

Since I have no idea what you are talking about, I probably need a little help. Right now it is in Word format and has some graphics inbedded. Probably 5 or 6 pages. It’s pretty solid because I have been editing it for 3 or 4 weeks. And I like the idea of Github for open editing

As you will see, it is written generic for most any home built router based machines with a little MPCNC specific thrown in. I don’t think there is anything else like it on the net because I came at it from a different direction. Not adapting mill machine to router, but adapting routing to milling metals… I plan to start up another forum thread to document my trials and ongoing learning. If I discover anything that violates the eng document, I will go in an edit. But at this point, the only thing I am still experimenting with is plastic deformation, fastener torque, and flex limits.

No problem. I wasn’t sure where you were coming from.

Just some quick language to help. Markdown is a way to format the text. Adding symbols will change the way it is presented on the page. Converting a complete document can be hard, but I am pretty fast at it. Editing a document that already exists is pretty easy, and I hope you try it.

Github is the website that we save the markdown document to. You will need a github account to edit the docs or post comments on changes.

Git is the technology github uses to keep the history. It defines some of the terminology we use, but you don’t need to know Git.

What works best is if you zip up the word doc and then upload it to a post here or in a new post. I will grab it and make a first version in markdown. Then I will submit a “pull request” (which is a request to make changes in github). Ryan and you and anyone else can look at it and make comments. Then it will be “merged” into the website automatically.

Then, if we find something new, or need an update, github will let you edit the text, upload new pictures, or reformat something. Any changes will end up as new “pull requests”. Github makes it as easy as possible.

Would one of the online markdown converters work to get the bulk of the document done?

I may have cut and pasted a document into a forum post such as this once, for an automatic markdown conversion, then copied and pasted it into a plain text document to save the markdown for use elsewhere.

> If it's ***ONLY*** a couple of pages, cut and paste the formatted paragraphs into the "reply" box and they'll look like this.

Might save you at least a little time?

It’s really not that much work and I need to read it anyway.

1 Like

Here ya go!
Milling Metals with MPCNC.zip (158.0 KB)

Looks good. I can open it and everything looks normal. I will get a PR up and then point you at it. Maybe in a day or so.

1 Like

I have basically just copied and formatted what you have. That is here:

It will end up looking a little different when it gets merged into the main docs, but you can see the main idea from the github preview.

I still have some work I’d like to do. Things like paragraphs read a lot different on the web, so I want to just break some of that up. There are some tweaks to add headings and subheadings, stuff like that. I should be able to do that tomorrow.

Quick question though. The images that you put in there. Are those all created by you? If any of those came from other sites, we can’t just use them as is. We either need to recreate a similarly descriptive picture, or we need to link directly to the original source.

And the docs are all licensed under creative commons. I’m just pointing this out because as soon as we merge it, this doc will be too.

2 Likes

I don’t care about the formatting. Whatever it takes to get it web based.

All of the graphics and charts are mine. I can change colors or reformat anything if needed.

Just my contribution to the community. All the stuff is out there open on the web, You can read multiple pages for every paragraph I wrote. The only value I add is selecting topics I think are relevant to mpcnc, and relating my experience with mpcnc.

3 Likes

I’ve read the whole thing a few times, and I think it is great. Very good quality for an addition to the doc and it lays out everything pretty well

I opened a pull request here: https://github.com/V1EngineeringInc/V1EngineeringInc-Docs/pull/221. We can have discussions there about it. Or, I also opened a forum post here: Milling Metals Documentation

I am going to put my first thoughts in the PR, but if you would prefer the forums, we can talk there.

DUDE!!!

Thank you so much that is awesome. I think it has all the info and it is presented very well for being actually pretty complicated. Sorry I missed this at first.

3 Likes

Thanks guys. I am no expert so this was really just a few weeks of reading and trying to understand for myself what is going on. I am an engineer, but this is a new topic for me. I was a little disappointed I could not find a write up similar. Most articles are written for all mills and just a few for all router mills… When my aluminum chips started looking like fingernails I knew I was on the right path.

I have a lot more stuff I will put in the forum when I get to it. I am constantly running tests to document and improve performance. But I was confident enough that with a little knowledge, others could duplicate what I have done with a basic machine.

4 Likes

I edited it a little bit in a few places and a little more on the multiple flutes section. I hope it is okay, we can merge it and you can take a look, if you would like me to change anything I will.