I love the Maslow Community, and I’m a big fan of Discourse as a forum platform. That said, the high volume of activity creates an enormous amount of information that is not always organized for easy consumption, especially for newcomers. The wiki function in Discourse claims to help with this, but I have not seen this to be the case so far.
There have been many times that I have wished for more traditional documentation. Given that I can’t write Python, this might be a way for me to contribute back to this community that has been so helpful to me.
I am imagining a documentation template (like MkDocs) in github, and we handle updates / changes in traditional git fashion. I’m willing to put time in on this, and we can expand the doc group as interested volunteers surface. Somethink akin to traditional open sources projects.
Below is a first ‘Table of Contents’ brainstorm. What else should we include? Once a basic framework is in place, we could ‘audit’ the forum for additional categories and content. Topics could link back to popular discussion threads that are topical.
I tried to do something similar and it is all in the wiki entry for the maslow manual, though not this complete. Feel free to take anything from that that is of use… I have more not yet included, but I’m doing other things right now. I like the mind map layout. If it had hotlinks back to relevant posts or wiki writeups / how-to’s that would be amazing.
We’ve got a discussion going over on the team channel for WebControl about polishing the user onboarding process. @madgrizzle has suggested that Bar is okay with WebControl becoming the “default” app for Maslow, which gives us an opportunity to polish and rewrite the onboarding flow. @cmullins70 if you’re interested in working together, I’m happy to do a lot of technical writing for the frame build + calibration process, and the maintainers of WebControl can help ensure it makes its way into that flow.
Very much so. It’s clearly superior at this point. I don’t see any advantage to the original Ground Control over web control anymore. I say we take the plunge and make it the official control software.
Great! We’re working on a plan for even further improvements right now (unfortunately, Github team threads appear to be private… but lots of movement happening there, especially thanks to @emilecantin for diving in to the technical). I’ll be working on the documentation (frame + calibration) side of things. If anybody else would like to collaborate on this, please do drop me a line.
Just curious… but is this work being done in a private group? Or am I missing something? Seems to me your loosing a lot of input from the majority?
Not complaining… but as one who has probably read every thread in the forums… I feel like I’m missing out on some of the best reading. I keep hoping that some thread may come along that I can have some serious input in. Even I have a good idea once in a while… lol!
I may be wrong in the purpose of a private group and if so… sorry!
It wasn’t intended as a private or exclusive group. Everyone was/is invited to the github webcontrolcnc site to help out with development of webcontrol and firmware. Private is the wrong word for it. it just isn’t this group. Those who have submitted software requests to github may have seen some of the issues, feature requests, or pull request conversations that are very software specific. Perhaps more of those that are less specific to software and Maslow in general should be pushed to the forum. Anyway, that was where the conversation started as a way to point the direction of development of webcontrol which as morphed into how the user experience can be made easier and more intuitive. I think at some point when each of us built our system and got up the learning curve, we had the desire to make it easier for the next person… at least I did. I tried to do some videos and a couple wiki entries to get things started, but it wasn’t a coordinated effort. This sounds like there will be many more hands and eyes on it to make it better. I agree and want to help with that.
I have been stubbing out here. I would appreciate thoughts on whether this should live on my account for now until it gets some momentum, or whether we should move the repo to the Maslow account. I’m new to the mechanics of contributing to a project. I would love to get those interested into to project and working.
Anyone is allowed to join the organization and have access to ‘teams’ communications… in fact, you can’t prevent it once you join the org. There’s a post on the webcontrol repository issues that talks about this. The problem is you have to find it and then post to ask for an invite. I’m new to github organization and it would be nice to have had better communications capabilities, but I guess github can’t do EVERYTHING…
I certainly don’t mind have most of the discussion over here since github isn’t really doing what is needed, but I would really like to restructure things such that there’s a webcontrol main topic and it have a subcategory list at the very top (like troubleshooting, feature request, etc.). I know it can be done in discourse because I’ve seen it on other discourse forums. This helps people to put a message in the right spot and keep things focused as such.
This is where “documentation” should ultimately be kept:
It’s sourced from the webcontrol repo itself. It has to be done a particular way so that its available both online (via the Internet) and offline (included within the webcontrol app in event your webcontrol server is not connected to the Internet).
With that said, anywhere the content is stored, wiki pages, forum topics, etc., we can transfer to the github pages and make it work… we just need content created.
I think that’s exactly what we’re doing currently? The doc pages are .md files in the webcontrol repo and github pages is pointed to those doc pages.
The challenge is getting things to work with both github pages and webcontrol at the same time. You have to create pages with images a specific way with those images stored in specific locations. But if you follow what’s been done, you should be ok. Someone may be able to figure out a better way of doing it, but how it is is how I got it to work…
Agreed with this approach, though I wonder if we could accelerate the progress by having a collaborative doc to get moving. I love Github (obviously), but I don’t think it’s a good mechanism for writing a quickly-evolving shared document. The PR process is too lengthy, and while it allows for comments it does not allow someone to propose an edit; once it’s committed, a whole new PR is required.
I was looking for a solution and came across https://hackmd.io/. It seems to be a nice Markdown editor that supports real-time collaboration—including comments—and integrates directly into Github pull requests. I requested to add its integration into the WebControl repo, but I’m not sure where Github sent the request…
I agree with this… that’s why I said that it should “ultimately” be part of the github. It’s cumbersome to do it via github repo and doesn’t facilitate collaboration.
I think I’ve almost got it working. I added a team and invited @madgrizzle
@cmullins70 can you message me your email address for adding?
It looks like the Github integration is almost working, except when I click next it says I must be a repository owner. @madgrizzle if you accept the team invite, just open a note and click the “Pull from Github” button in the lower left to trigger the auth flow.
