We have talked for a while about what the best way to store and display community information is and it seems like we really need a central space, at the moment we’re too spread out over too many places and it makes it hard for folks to contribute.
I think that the best way is to have a single github repo which has all of our software (both the firmware and the UI) along with spaces for a wiki and things like the assembly instructions.
I chose to keep the fork from FluidNC as the base repo because we might want to update from the main branch at some point, and I want to maintain the connection to all the work that those guys did in building FluidNC.
I will start working on migrating everything like the assembly instructions over to that repo so we can keep everything in a single centralized place.
getting things tied together under a single git repo is a good idea, and will
make it much easier to keep things consistant.
If we do this correctly, all of the git history will still be there in the new
setup.
The only question I have (that I’ve raised with Bar before) is if this should be
implemented as a single repo or as a master repo with submodules
using the submodules will mean that the instructions to set it up are a little
more complex (but people just cut-n-paste those anyway) and there will be some
new management scripts that will need to be tweaked/improved. But if/when we
start working with new versions of the upstream repos and get to the point that
we can sync with them it will be easier.
It may be possible to setup scripts to combine/split repos after the fact. so
it isn’t necessaraly a final decision.
I know enough git stuff to know the technology, but don’t have enough active
development work to know reasons why it’s a bad idea
I’m leaning towards single repo just because of the way the AI stuff works. It would be awesome to be able to request a new feature and have it update the firmware, UI, and documentation all in one go
@wouldchuck and I are trying to figure out how to better organize our documentation and information.
Our current system is that most of the information (assembly guides, user guide…etc) are static pages on our website hosted by Squarespace.
That is bad because:
The information is not community editable so we are missing out on valuable chances for it to be improved The information is often out of sync with the current state of the firmware
We have two better places that we can store our information.
Pros: These files look and work somewhat similar to the existing web pages Edits to these files are suggestions so we can be sure that our files there won’t have changes which are wrong The @MaslowBot AI can make changes here automatically so a change to the software could automatically be reflected in the user guide keeping things in sync
Cons: Editing can be a bit of a pain in the butt for users who aren’t familiar with github
Pros: We used the wiki for all of our documentation in the first version of Maslow and it worked well Anyone can make changes and improvements
Cons: The AI cannot make changes to the wiki
What are everyone’s thoughts on where our information should live?
I’m leaning towards putting the more fixed documentation (Assembly Guide and User Guide) in markdown files and putting things like a list of different frame designs in the wiki, but maybe that is too spread out and everything should be in the wiki.
I know very little about Github but have been trying to copy over the instruction manuals to a markdown file and start an outline of a comprehensive manual where we can collect the wisdom from the forums. It would be a long file but maybe a single place is good and then it can be pulled from to make manuals and getting started guides. So far I have outlined a general table of contents list and copied over the software user guide and most of the instructions for building 4.0. I am happy to keep manually pulling over the instructions to make sure they are correct or we can play with the ai to see if it can pull things over in an accurate way.
Here is my repo, if we make something useful it should probably be moved to the main repo.
Here is my proposed general table of contents. TABLE OF CONTENTS
Things you will need to get started
Optional but good things to have
Safety and hazards
Forums and github
Build instructions
Tips for building 4, 4.1
Details of optional upgrades
Routers lists and library
Router bits lists and library
CNC, CAD and CAM software lists and library
Material to cut lists and library
Frames and frame library
Connecting to the machine
Updating the Firmware
The Control panel and software
Other things you can control in the software.
Ancohors and calibration
Moving the robot around by jogging
G-code
Feed rates library
Test Cut designs and grids
Making a 2D design as a vector drawing .svg
Changing a 2D design into G-code .nc for cutting
Uploading G-code .nc to the machine
Fixing the work to the wasteboard
Inserting a cutting bit
Inserting a drawing pencil or pen (no idea how to do this)
Drawing with the machine
Preflight check
Cutting a 2D design
Designing a layered 2D design with mulitple depths
Preparing a layered 2D design as G-code
Cutting a layered 2D design with multiple depths
Switching cutting heads between operations
Designing a 3D sculpted surface design
Preparing a 3D sculpted surface design as g-code
Cutting a 3D sculpted surface design
Designing a 3D piece of furniture from multiple 2D panels
Abundance software
Paramaterized design for 3D
G-code for furniture
Cutting furniture.
3D design as stacked layers
Cutting 3D as stacked layers
G-code for stacked layers of 3D designs
Other design methods
Including bushings and hardware in designs
Design library (perhaps one for parts of designs and one for full projects? )
If there is a better way to organize things in Github that could be good. I would suggest that whatever we do it would be good to keep links and files only one or two layers deep to keep a manual readable and accessible.
I don’t really understand what I am looking at here
Is this meant to be a master repository for all things maslow? Can anyone make changes? I don’t want to vandalize something that is important to someone. For instance, could I change the tagline to something like “Open source project for an affordable and accessible Belt driven CNC 3 axis Router” ? Would a user manual be a file under docs? Is it ok if I put one there? Can we change the Readme?
I would like to help with instruction manuals and collecting information. I would like to stay away from the programming and technical work so that I don’t clutter up the really useful work there, What is the best way to get started? Do I make a fork, change or add a document and then make a pull request?
I would like to help but am confused about how to get started. Even if I figure out Github mechanics I don’t know what would be reasonable for the repo above. As a mostly non progamming community member I don’t know where to start.
I’m leaning towards single repo just because of the way the AI stuff works. It
would be awesome to be able to request a new feature and have it update the
firmware, UI, and documentation all in one go
with submodules, everything will look like it’s in one repo, but the process of
comitting changes is a bit mroe complex (but that should be automated.
we would need to experiment a little with how AI sees this.
Pros: These files look and work somewhat similar to the existing web pages Edits to these files are suggestions so we can be sure that our files there won’t have changes which are wrong The @MaslowBot AI can make changes here automatically so a change to the software could automatically be reflected in the user guide keeping things in sync
Cons: Editing can be a bit of a pain in the butt for users who aren’t familiar with github
Pros: We used the wiki for all of our documentation in the first version of Maslow and it worked well Anyone can make changes and improvements
Cons: The AI cannot make changes to the wiki
What are everyone’s thoughts on where our information should live?
I’m leaning towards putting the more fixed documentation (Assembly Guide and
User Guide) in markdown files and putting things like a list of different
frame designs in the wiki, but maybe that is too spread out and everything
should be in the wiki.
having the documentations and instructions versioned along with the code is a
good thing, it means that if someone needs to dig up instructions for an old
version, they can look at that version of the docs (something you really can’t
do with a separate wiki)
yes, right now we are thinking that everyone should upgrade to the current
firmware, but that may not always be the case (and sometimes you need
instructions to find out how to upgrade, so far those have not changed, but if
they do, how does someone find the instructions for their version)
I’m not that worried about the complexity of people making updates, we can’t
just let anyone update the wiki due to spam problems (not to mention just
consistancy), and it’s not hard to train people on how to update via github
(especially if they can just tell the AI what they want to change)
It is meant to be a master repository for all things Maslow but because it started out as a FluidNC repository it still has a lot of FluidNC stuff that we need to replace.
Anyone can propose a change but those changes have to get approved which makes it really easy to not worry about breaking anything.
We probably need to copy that over to this repository.
That would be a great place, and yes please! I had the AI copy over the web page from our website so there should be one in there already, but it probably needs work.
YES! I think that this would be a good place to start. The Readme is the main thing that shows up on the front page so it should have the most important information and links that people are most likely to need.
I think that the first place to start is to update that readme. I think that everything which is currently in the README could be deleted or maybe moved to a dedicated FluidNC.md file
Feel free to start out by making a pull request to change just about anything to test the process out and see how it works. Don’t worry about breaking anything, the system is set up so that you truly can’t do anything wrong.
It is meant to be a master repository for all things Maslow but because it
started out as a FluidNC repository it still has a lot of FluidNC stuff that
we need to replace.
we don’t want to mix everything at the top level directory, start by moving
everything down one level
mkdir firmware
git mv * firmware
git add *
git commit -m ‘move firmware down one level’
otherwise we will have build stuff for the UI and the firmware and the docs
tangled together in the same directory.
the current README.nd is pretty specific to FluidNC (including asking for
donations to the FluidNC project), so I would have it in the firmware directory,
with a new one at the top level that’s talking about the maslow specific stuff.
I would consider splitting the docs between developer docs and user docs (what’s
needed for people working on the code vs the instructions for the people just
wanting to use the machine)
using git mv, git handles that better than you would fear. But if he’s working
on a re-write, no rush to move the existing one.
next step put the UI under /ui ??
then make a build script at the top level that makes both (and puts them in a
top level /builds directory in addition to their existing locations) ??
Also, I noted that the resulting build was just named v1.15 rather than
v1.15-11-g757b0dd4 I think I made a PR to fix the field overflow bug and allow
long version numbers. (and see my long post on versions in the Branch Branch
Revolution thread)
The information is not community editable so we are missing out on valuable chances for it to be improved
These files look and work somewhat similar to the existing web pages