Documentation writers needed

[thinkyhead]

The Marlin Firmware Wiki is up and running, but far from complete. There's a lot of documentation that needs writing. I've written several pages to get things rolling. The pages that should be easiest to do, but require the most attention are:

• G-Code and sub-pages like such as G1, G2, M0, etc. (to be used as templates).
• The Marlin Configuration page documenting all of Marlin's configuration options, based on comments in configuration files. (Bigger features also get their own dedicated topics.)
• The Bed Auto Leveling, Mesh Bed Leveling, Delta Kinematics and other pages on high-level concepts related to Marlin.

[fmalpartida]

Nice one! El 16/5/2015 12:26, "Scott Lahteine" notifications@github.com escribió:

The Marlin Firmware Wiki http://www.marlinfirmware.org/ is up and running, but far from complete. There's a lot of documentation that needs writing. I've written several pages to get things rolling. The pages that should be easiest to do, but require the most attention are:

• G-Code http://www.marlinfirmware.org/index.php/G-Code and sub-pages like such as G1 http://www.marlinfirmware.org/index.php/G1, G2 http://www.marlinfirmware.org/index.php/G2, M0 http://www.marlinfirmware.org/index.php/M0, etc. (to be used as templates).
• The Marlin Configuration http://www.marlinfirmware.org/index.php/Marlin_Configuration page documenting all of Marlin's configuration options, based on comments in configuration files.
• The Bed Auto Leveling http://www.marlinfirmware.org/index.php/Bed_Auto_Leveling, Mesh Bed Leveling http://www.marlinfirmware.org/index.php/Mesh_Bed_Leveling, Delta Kinematics http://www.marlinfirmware.org/index.php/Delta_kinematics and other pages on high-level concepts related to Marlin.

— Reply to this email directly or view it on GitHub https://github.com/MarlinFirmware/Marlin/issues/2090.

[JustAnother1]

Does it make sense to hhvae G0 documented here here and in the Marlin Firmware Wiki ?

[thinkyhead]

Does it make sense to have G0 documented here here and in the Marlin Firmware Wiki ?

@JustAnother1 Yes.

The documentation at the RepRap wiki is getting stale, even more for other firmwares than for Marlin. And we haven't up to now had a location for detailed discussion of the many details of Marlin. Plus, it would be poor form to document Marlin in its own wiki and not include full documentation of its G-Code. And, we are adding new codes which are in their nascent stages. It will be good to have a more definitive reference – specific to Marlin – that is under Marlin control while we work that out. Finally, the documentation we are writing here is in MediaWiki format also, and will be easy to migrate to the RepRap wiki, should we decide to do so. But I would rather not pollute the RepRap wiki with the far more detailed descriptions of Marlin G-Code, where we discuss how they behave in Marlin and include implementation details, since they are uninteresting to people reading the RepRap wiki G-Code page for a more lightweight reference.

This is good to see (http://reprapcode.haz.wiki/command/g0) though, and I may plagiarize liberally from that as well. Whoever maintains that site, its very nice of them to make it! :wink:

[JustAnother1]

@thinkyhead It was a rhetorical question and the answer is NO !

The G-Codes are not part of Marlin. They are the interface between a firmware and a host. They are also the interface between a firmware and a slicer! So neither part of the firmware nor the host or slicer!

So it is totally fine for Marlin to say we fully support the G-Codes defined there.

By the way the documentation you want to steal was done by @foosel (Octoprint) and her Idea for doing this was to have only one documentation for G-Codes. If you like her documentation then put a link into the Marlin wiki and add your stuff to her wiki!

[foosel]

...

[Jnesselr]

@thinkyhead I think it's very dangerous to put something like this under the control of a specific firmware mostly because you're likely to change something in regards to how the protocol works to better fit Marlin. Also, it will then become the Marlin standard of gcode instead of something everyone can use.

I know the same issue can happen with @foosel in control, making it convenient for the host side and not for the firmware. We're trying very hard to have both host developers (of which I am one, although I currently use printrun's core) and firmware developers work together to create an interface that works well.

If you start documenting how marlin handles things currently, then that could be fine as a reference, but don't do it as the definitive specification of the protocol. We're already very separated in terms of protocol and any form of standard at all. This is hurting our intended user base greatly.

My hope is that one day people will literally have a plug and play printer. Right now we're more interested in cheap printers than actually making quality machines with a lower learning curve. I'd love it if a host could also update the firmware for the user. Ie, host gets a url from the firmware, looks it up, then requests configuration info from the firmware and patches it up to the next version much like up/down for a database before writing it back to the device. This is just one example of a higher level function that we currently have no way of organizing but would be great for vendors like printrbot or aleph objects that would want to update their users' firmware automatically with bug fixes.

[wijnen]

I agree with @JustAnother1 here. The idea of having different options for host software and firmware which all communicate with each other can only work if they speak the same language. That language is not owned by any one of those programs, it's a standard.

I also understand the need for implementing experimental features, and it is good to document those. Being experimental, they aren't part of the standard.

So I would suggest to fix the wiki on reprap.org (or the place @foosel created, or the new consortium place that's about to be created; anything goes as long as it's just one place) with up to date information about non-experimental features, document the experimental ones here as part of Marlin and point to the standard for all the non-experimental ones.

As a programmer, you should know that code duplication is bad and leads to out of sync information. This is no different for documentation. So you should avoid it. The standard is not owned by Marlin and should thus not be documented here. Experimental features are, and should be documented here.

[thinkyhead]

the documentation you want to steal

Yes, that's why I announced my intention with a wink. Because I want to steal it.

I contribute a lot of editing to the RepRap wiki. Don't mistake my intention here. I want to make good documentation and improve it to the best of my ability, and contribute back. It's all open for sharing. If it helps, I will hide those pages while I work on it.

[thinkyhead]

I'm working some new codes, which of course are free for the other firmware to adopt or not (GPL!). This is the latest, M33 #2108 I will have to document this one first, because I'm inventing it….

[thinkyhead]

because you're likely to change something in regards to how the protocol works

That is very unlikely, given the community's conservatism around alterations. It takes a lot of consensus to do that. "Protocols" will certainly not be changing without a lot of collaboration among groups. As for adding new codes, those are not problematic since no slicers or hosts yet know about them, and only pick them up once they are mature. Again, the whole point of my creating an issue here around a Standards Consortium.

[thinkyhead]

This is no different for documentation. So you should avoid it.

In this case my point is to create definitive documentation that is up to date. I was not at all aware of the work by @foosel or @JustAnother1 – or their apparent higher rank in the RepRap world. I was only aware of the RepRap wiki and its (very bad) GCode page, and wished to start over from where Marlin is – and then I intended to migrate that work to the RepRap wiki. Now that I am aware of the other work that has been done, I can go back to building Marlin for all you wonderful folks.

[wijnen]

@thinkyhead Please, don't be so defensive. Everyone agrees that we want good documentation, and your efforts are appreciated. That doesn't mean we must agree with your course of action, though. If you also agree that the protocol should not be documented as a part of Marlin (that has nothing to do with rank, it also shouldn't be in the Octoprint repository), then why would you work on it here at all? Isn't it easier to do it in the place that will host them eventually? Also, given that @foosel is still working on that page, why not help her out instead of copying parts and then improving your copy, thus depriving her from your improvements? It's a wiki, you have (or can get, if you ask) write access there, too.

I fully understand and encourage your wish to document your work, and I agree that such new extensions should be documented here, at least until they are accepted as standard. What I'm saying is that you should document only those codes, and not copy the standard into here; that only leads to out of sync documents. Instead, if you want the standard to be easily accessible from the documentation here, link to it.

[thinkyhead]

doesn't mean we must agree with your course of action

Just give me the benefit of the doubt, for chrissake.

[AnHardt]

My opinion about g-code descriptions on a Marlin pages is: 'The descriptions are not meant to be a standard, but should describe the Marlin interpretation of the commands'.

@fmalpartida We desperately wait for your promised article about the branches. (A closed issue is not the ideal place). If you can't find a good place - just take https://github.com/MarlinFirmware/Marlin/wiki. One of the few with write access to http://www.marlinfirmware.org/, for sure, will integrate it there. Or ask @Scotty1024 for an account.

[thinkyhead]

Isn't it easier to do it in the place that will host them eventually?

It was easier to do it in private before I announced it. But more to the point, it's in Wikimedia format, which can be scraped as HTML, and easily grep-replaced to make it into any suitable format.

[thinkyhead]

why not help her out instead of copying parts and then improving your copy

Perhaps I would prefer to be concise, and leave discussion of related topics to their own dedicated pages.

[thinkyhead]

thus depriving her from your improvements?

She is free to copy and paste from my work as well, and –now that I am aware of that page– I would of course share my work. In spite of my cheeky comment about plagiarizing, I have preferred to write out the explanations myself in good concise English without influence from other documentation. Again, my process is faster if I slog through – I'm not just copying and pasting from other sources, but composing it using the source code as my guide. – Or, rather, was composing it.

[Jnesselr]

@thinkyhead before you announced what exactly?

Also, have you looked at the wiki that we're making? Like, at all? I don't mean to be rude, but we're being pretty concise and keeping things on their own page and they have a discussion module. It seems to me that you want to make your own version where you don't have to work with other people.

[thinkyhead]

have you looked at the wiki that we're making? Like, at all?

@Jnesselr Like, no. I just found out about the wiki you're making. Tell me more.

It seems to me that you want to make your own version where you don't have to work with other people.

@Jnesselr It seems to me you have a very cynical view and that you and @JustAnother1 are being unnecessarily accusatory.

before you announced what exactly?

Before I announced that you're obnoxious here that documentation of Marlin was happening.

[foosel]

Before I announced that you're obnoxious

Classy. You really have a way with people.

For content, what @wijnen said:

As a programmer, you should know that code duplication is bad and leads to out of sync information. This is no different for documentation. So you should avoid it. The standard is not owned by Marlin and should thus not be documented here. Experimental features are, and should be documented here.

[thinkyhead]

Classy. You really have a way with people.

I'm sorry, but the statement I was responding to was, by dictionary definition, obnoxious, and designed to be so. And frankly I'm not interested in all the politics and personalities. I posted to let you know there's a Marlin wiki. I explained I had done lots of work on it to get it started. And then a bunch of obnoxious comments started flying about how awful I was for doing so.

Try to comprehend this from my point of view. I have been devoting immense amounts of time to improving Marlin and pulling it out of a stupor, and I am not in the mood for brand new voices who have not been my kind friends here along with me, suddenly dumping on me over some offhand comments —intended to be a friendly wink— misinterpreted as some kind of malicious declaration.

It's screwy, and I'm not down for it. So, please talk amongst yourselves while I go cool down. You have really irritated me with all this nonsense, amounting to: the Marlin project shouldn't be allowed to document its G-code implementation for its own reference – at least not publicly. Ok, well I will hide it for the time being, but I find the process valuable as someone writing the code, and I would like to perhaps use it in the future to produce a quick-reference card. Who knows?

And of course my intent is to share the work, the point of this topic.

Thank you for your valuable input, everyone.

[foosel]

Ok, I see where you are coming from, but I don't see obnoxious comments above. People told you where they thought you were wasting energy. No one said anything about forbidding you to document stuff, but they informed you that it would make more sense in a different way. If you can't take that kind of critique, I have some bad news for you, because it will only get worse from here. You are a collaborator on a high profile Github project. That entails also the ugly things such as politics and personalities, and having to tolerate stuff you might not want to hear, brought up by people who sometimes might not have the most diplomatic way of phrasing it (we want to get stuff done here, that means you sometimes have to get information across without the time to try to not hurt any feelings). It also entails getting to know your environment and with that I mean what's going on around you in the community. You have a responsibility now. It's not just writing code (in fact, on some days it's anything but), some times it's talking with people, trying to understand their worries and points of view and finding a good middle ground everyone can be happy with, and of course sometimes it's also staying on top of current developments.

If you are doing things in a way that people don't like, and they tell you that, well, extract the constructive criticism and try to do it better instead of getting cocky or offended about it (or calling everything but your own interpretation broken until convinced otherwise, as it happened with the G28 thing). Because if you don't learn this, you will not have a lot of fun I fear.

And especially in an open source context, you never joke about stealing aka taking other's work without crediting. A lot of us have found ourselves on the receiving end of exactly that happening with our work for real, so unless in very very special situations, best avoid it.

That being said, now maybe try to comprehend it from our point of view. Because I don't get the feeling you did. @JustAnother1 told you about another documentation effort aiming at a standard (which in fact you should already have been aware of). You promptly brushed it off as "oh, nice, but" and "I'm going to copy that" (the smiley can be read two ways btw) and insisted on still doing the work twice (btw, I'm not even of the opinion that the "default" commands shouldn't be documented as long as there is no standard, but once there is, a simple "conform to ..." should be all that's said there, for reasons that were already stated). People then started telling you why that would result in duplication, things getting out of sync and probably more problems then anything else. Which you first just completely played down (no, it's not very unlikely that if you don't refer to a standard that commands will diverge from it - it has happened before) and then took personally and started lashing out ad hominem. And that's a behaviour I'm sure I'm not alone with finding very unfitting here.

[Wurstnase]

I can understand both positions.

But why shouldn't have Marlin its own documentation of the gcode? Any gcode which is already the same as the 'standard' can be marked as 'allready implemented like the standard'. When the standard is finished we can work on the implementations, so any gcode is how it should be.

But there will be anytime some gcodes, mcodes or whatelse, which are independend from the standard. Like G29 for example.

Some people here are going to be very angry without any good reason. Discuss it, but be fair, nor?!?

[thinkyhead]

@foosel Yes, I am thin-skinned. How could I ever get bothered by statements like...

the documentation you want to steal

…or consider overly alarmist…

very dangerous to put something like this under the control of a specific firmware

you're likely to change something in regards to how the protocol works

All this paranoia, directed at my attempt at being helpful and just bloody documenting the source code, is what has been bugging me. I'm sure you're all very nice, but take it down a notch. You people don't know the effort I've been putting in, don't seem to appreciate it, and I am hard-pressed to attend to all these concerns with patience and sympathy at the moment, or respond with perfect fidelity. Give me time.

Meanwhile, I am very much inclined to keep documenting Marlin's current implementation of G-Code for the Marlin project, and I don't mean to downplay your concerns, but they are truly overblown. No one is planning to take over RepRapistan. I just don't get where that is coming from.

[foosel]

You people don't know the effort I've been putting in, don't seem to appreciate it

Sorry, but neither are you. The people commenting here are not people who are just waiting for everything to fall into place while needlessly criticizing from the off. We all are heavily invested into this stuff and are spending most of our waking hours trying to make 3d printing a better place.

The first thing I ever consciously saw of you was a comment on the G28 thing which one of my users ran into what got me looking into the bug tracker in the first place and where you were not acknowledging a mistake you'd made but instead taking the stand that all host developers are apparently slobbering idiots who don't understand the command or the "protocol" and who should now fix it on their end. Talk about a positive first impression (and that you hadn't yet discovered the bad-but-the-only-thing-we-have reprap wiki page didn't make it exactly better). It's ok to make mistakes. It's ok to not know things. It's not ok to not acknowledge both in such a critical environment.

And

you're likely to change something in regards to how the protocol works

You are calling this paranoia and interpret it as something born out of distrust towards your intentions. Again, it is not. We just know from experience that when you keep things documented at two different locations and only refer to one of those during development (which can happen bloody fast) it will happen that you introduce breaking changes (as has already happened). Not because you mean to break stuff but because it just accidentally happens. It is something that is bound to happen if you do it like that. You can't possibly keep all things in mind all the time (at least I wouldn't dare to claim that), and this is what has people here worried, that you'll change something not out of mean spirit but just because the documentation you are looking at doesn't spec it very well which has nasty consequences all across the board.

The problem is that you take things being said here as being targeted at your person and your intentions when it is fact targeted at management and project organization.

I'm sorry if this isn't the environment you were hoping for, but as I said, what you are doing and how you are handling the project influences a lot of people out there, so you shouldn't be surprised that they add their 2ct from time to time.

In case you think that I enjoy having to go through the source code of three plus firmwares regularly just to make sure everything is still working as expected there, in order to prevent my users from running into problems when they flash their printer next time, you are mistaken. Documenting my API and now the transport protocol? Fun is something else entirely. And don't get me started on discussions like this ;), stumbling across Kickstarter campaigns that show obviously ripped off versions of OctoPrint or entitlement among the users screaming bloody murder at me because their super important feature is still not implemented in that piece of software they don't pay a fine for. But all that is part of a widely known open source project, so you gotta learn to handle it as best as you can (note that I wouldn't dare to assume that I know how to handle it) without what has happened here.

[thinkyhead]

@foosel I'm here to help, whatever you need.

[thinkyhead]

it will happen that you introduce breaking changes

Not to a release. To development, definitely possible. And, I never called anyone idiots, I was merely confused by the protocol at an early point, and thought it should be more sensible. And of course it could be, with consensus, if I was not alone in my view. And, I was new to this project when G28 got its proposed extension, and it was put out there for testing. After a long break, I thought it had always been that way, that the G92 behavior mixed in was part of the specification. Anyway, I learned how it was supposed to be and fixed it. All of this has been happening as part of the bug scrub period that I proposed ahead of the next release. Everything has been in more intensive testing as a result of those efforts, because naturally I want to know where mistakes may be. You will find the protocols have been brought into better compliance than ever under my stewardship, and you will see that the quality of the work and code has also improved. I am, as I say, here to help and to leave this project better than I found it.

[thinkyhead]

but don't do it as the definitive specification of the protocol

@Jnesselr That is not anyone's intention. It is just to have the Marlin implementation documented.

[foosel]

[Testing]

No. Testing can never find all bugs. It can never proof that your code is bug free. It can only show you where there are bugs you anticipated in one way or the other beforehand and help you minimize them.

But you should never just shoot off changes assuming that "Testing will show if that stuff is correct or not, people will come running and complain" (that is a great way to get people riled up). Your goal should always be to have stuff in working order all the time (WIP branches taken aside). And especially with the testing that it's currently in place on this project here, which is not even a compile test for all possible code variants, let alone a proper integration test (and before anyone starts pointing fingers, I know I have to clean in my own yard there too).

So, all I'm saying is, please acknowledge that there are people here who also want to help, so calling them names when they disagree with you and/or tell you that you are mistaken is probably not the best way to keep on getting free advice from people who've been in similar situations.

Which you'll need. I've been there too.

[thinkyhead]

trying to understand their worries and points of view and finding a good middle ground

And I do that very well when people ask questions before they start shooting. This has all caught me off-guard after two weeks of working on Marlin and the wiki in a binge without much sleep, and finally having the wiki in a state where it's worth bringing in front of others. Of course I appreciate everyone's fabulous efforts. I hope you appreciate mine after the 1.0.3 (or possible this might be 1.1) release.

[thinkyhead]

@foosel BTW thanks for the critique on my recent combo PR. I have been honing my cherry-picking and merging skills and producing much more exemplary PRs for the last couple of days. I hope I'll be seeing you around here more often.

[JustAnother1]

@thinkyhead I'm very sorry if my comments made you feel bad. I have seen you around, and know that you do many good thinks for Marlin. A big thank you for that!

I know that I'm sometimes to harsh with my words. But my intention is not to hurt people, but to find a efficient way to get my points across. It like @foosel described most of the time a efficient way to operate in open source projects. I'm sorry if that causes misunderstandings and hard feelings. I promise to try to become better in the future.

Besides that I think we are more or less on the same page here. We all want to improve 3d printing. I think @Wurstnase made a good point about describing only the things that Marlin does differently than the (yet to be created) standard and for all other to just refer to declare as being conform to the standard.

The title of this issue already implies that we have too few people actually doing documentation. So we should try all we can to not waste the work of these people on writing the same thing over and over again. I'm with @wijnen here. Lets join forces and put the not firmware dependant part of the G-Code definition to a central place. That way we all can work together and get better documentation with less effort. Also lees effort for the hosts and slicers. And I'm sure we can come up with a good way to extend the standard with new command whenever the needs arises. And we will be able to do it in a way so that not only firmware developers but also slicer and host developers wont have a hard time adding the new command to their projects.

I would be very happy if you would join this effort so that we can make it happen.

[thinkyhead]

No. Testing can never find all bugs.

I didn't mean to suggest that it could find all bugs. But hey, there's more testing, fwiw.

[thinkyhead]

never just shoot off changes

Thanks. It has been months. I have that lesson. You really have it in for me. :disappointed:

[thinkyhead]

to have stuff in working order all the time

Getting better at that all the time. I spend so much time with this code, and going over and over fine details with other developers, having good collaborations, figuring things out. It has been going very well, getting better all the time.

[thinkyhead]

calling them names when they disagree with you

I can take a couple, but I was not prepared for the onslaught, and I was at the end of my patience with jibes. "before you announced what exactly?" I want to have a t-shirt made with that on it now.

[foosel]

No, I don't have it in for you!

I admittedly was a bit miffed at that but I wouldn't have mentioned it if I hadn't read your comment above as "There will not be any bugs in stable versions because we will all find them through testing". Just doesn't work, at all, not even slightly (personal experience). You haven't lived until you've had a critical bug in production affecting around 3 million users (5h phone conference with live patching...), that really makes you hilariously careful even on WIP branches ;)

[thinkyhead]

makes you hilariously careful

How careful am I not being, exactly? My M33 PR is a work of staggering beauty, as is my other pending PR. Can I get some props?

There will not be any bugs in stable versions because we will all find them through testing

I did not intend to suggest that is my thinking. Really, I think some people came in here with an ax to grind. Uncle!

[Jnesselr]

Okay, everyone, enough. @thinkyhead We're not trying to attack you, but we're trying to help in areas where we've found problems before. Also, a sour taste was initially introduced when discussing stealing things because that's something very near and dear to us. I apologize if we're coming across as attacking you. That is not our intention.

@foosel Let the man document Marlin. If it comes out different and out of sync when the standard does exist, we can talk about it then.

For now, please stop this discussion (if not the ticket since it's not related to the discussion) because both of you are angry and not getting anywhere.

[thinkyhead]

a sour taste was initially introduced when discussing stealing things

I've been doing FOSS for about 20 years now (oh my jesus) so – hello – let me introduce myself…

In 1986 I wrote a game called "Dino Wars" for the Amiga platform, followed by the Amiga version of "Bill 'n' Ted's Excellent Adventure." You can now download both for free and run them under emulation… I made about $3000 from both games combined. It was at the tender age of 11 when I got my first Sinclair ZX-80…etc. etc.

I thought that among like-minded people in the sharing community, it would be obvious that I was being facetious when I used the word "plagiarize." I see that I must be more "Scandinavian" in my approach to communications…

[thinkyhead]

@JustAnother1 Thank you for your support and compassion. I agree that the focus on marlin wiki should be: this is how marlin 1.0.0 worked, and here's what works in marlin 1.0.2, and here's what is new (developed based on lots of input) in 1.0.3… And of course all about configuration. That's a topic I hope to see develop into a proper manual.

I was never personally intending to shut anyone out any conversation about how the firmware evolves. And I'm just one volunteer. New features aimed at hosts or that affect printing need time to mature, and really, it's only when hosts and slicers decide to adopt these features that they will ever gain any traction.

I do understand the problem of fragmentation, and that too is part of what I hope will come from bringing all these projects to the same table. And, I have been gratified to see pretty much all the developers of the major hosts, firmwares, and slicers show up to discuss things and explain their needs, and it has given me quite a full education.

Our focus the last 6 months has been on making a whole out of many disparate parts within Marlin itself, and the wiki was only launched through generous donation a month ago. It has been pretty much just myself doing the bulk of work on the wiki so far, and there are always issues, more issues, and it's maybe taking some toll, but I seem not to mind - yikes!

I would love to get some of that BQ developer support because I am about to become homeless from my Marlin obsession…

[wijnen]

On Mon, May 18, 2015 at 03:58:20AM -0700, Scott Lahteine wrote:

All this paranoia, directed at my attempt at being helpful and just bloody documenting the source code, is what has been bugging me.

As I describe later in this message, a part of the documentation you are writing is actively harmful to the community. That's why people like myself try to convince you not to write that part.

That is not an attack on your person, or mistrust of your intentions. We like that you help improving the open source 3-D printing community. But we disagree on the way you are doing it in this case, and so we try to convince you not to do it. It's not personal. You're a nice person, as far as I can see. And you're doing good work.

But when you make a mistake (because everyone who does things makes mistakes), please own it. Just say "yes, I was wrong about this, I changed my mind and will do it differently", or explain why you aren't convinced and still think your idea was right. Don't say any of these: "their apparent higher rank", "It seems to me you have a very cynical view", "you and @JustAnother1 are being unnecessarily accusatory", "I'm not interested in all the politics and personalities", "how awful I was for doing so".

Even if those statements were true, and you were being attacked (which is not the case, AFAICS), they don't help anything. They only make people angry and nothing gets done.

You say you don't want to handle people's personalities and just do technical things. That will cause you trouble, but that's your problem. If you want to talk about technical things, then please respond to and with technical arguments. I've explained why having this documentation is a bad thing. I'm explaining it again in this message. I'm also explaining why there is no need for it (so it's not a choice between two evils). Please either say that you agree (and then don't write that documentation), or explain why you don't, so we can have a technical argument about it.

I'm sure you're all very nice, but take it down a notch. You people don't know the effort I've been putting in, don't seem to appreciate it, and I am hard-pressed to attend to all these concerns with patience and sympathy at the moment, or respond with perfect fidelity. Give me time.

If it's just time you need, that's fine. But please do respond to the actual issues at some point. And don't worry about defending yourself; you're not being attacked.

Meanwhile, I am very much inclined to keep documenting Marlin's current implementation of G-Code for the Marlin project, and I don't mean to downplay your concerns, but they are truly overblown. No one is planning to take over RepRapistan. I just don't get where that is coming from.

I am not worried that you are trying to take over. I am worried that what you do results in broken printers. I'll explain how that works:

• You maintain a copy of the standard in Marlin's repository.
• Either your copy, or the standard, is changed (better wording, fixing something that was actually wrong, whatever).
• You, or someone else working on Marlin, wants to improve the code and looks at the local copy.
• Things are implemented that don't fit the standard.
• Hosts do follow the standard, and unexpected things happen.

Because of this, having a copy of the information in Marlin's repository isn't just a waste of resources; it's actually harmful. Keeping this copy private is less harmful (because now only you can make mistakes based on it), but still harmful.

You have offered a technical comment to this (thank you!), so let me respond to that:

You say that you want to document Marlin's implementation. I argued above that this is actually harmful, but I'll also argue that you are mistaken in wanting this in the first place.

There are two types of implementation: features that are in the standard, and extensions. For extensions, please do document them. Marlin's repository is the proper place for doing this. There is no disagreement on this.

But for features that are part of the standard, what's the value of documenting what Marlin does? Either it follows the standard, in which case you can simply point to the standard as documentation of the feature. Or it doesn't follow the standard. That is a bug, and it should not be documented; it should be fixed.

Therefore, the documentation for Marlin should consist of a link to the standard, plus an explanation of extensions.

[Wurstnase]

Why not documenting that in the Marlin documentation? There are a lot, if not most, users who are not interested in such standard or not standard-things. They just want to quick check which command they need for doing this or that.

If you have 3 or more sites to check each command, is that what you want?

User 1 checks the wiki from reprap.org and find most commands but not the newest. User 2 checks marlin wiki and found just special commands and thinks that shit. User 3 checks standard-gcode and will never find some special new command.

Or User 2 checks marlin wiki find all commands with special commands and is happy.

Sure this needs also some work.

The 'standard' should be the cooking recipe for developers. Not the manual for users.

[wijnen]

@Wurstnase Because:

• It makes no sense to make Marlin the authoritative source for this information; why Marlin and not any other firmware or host program?
• It must not be in more than one place, because the copies WILL get out of sync.
• The internet has links. If a user (including a developer) is looking for how things are working in Marlin, they can go to the Marlin documentation. That lists the extensions, and a link to the standard. They click it, they are happy.

So recapping: Benefits of my approach: everything works, everybody is happy. Downsides: users need to click a link to get to the standard when going to the Marlin documentation to get it.

Benefits of your approach: They don't need to click that link. Downsides: Everything breaks.

I'd say that's a pretty easy choice to make.

[JustAnother1]

If we have a standard up and running that would probably be a good time to retire the reprap Wiki page (Add a big disclaimer with a link to the standard or delete it altogether) That solves User1.

The suggestion was always to say in the Marlin wiki that Marlin in compatible to the standard (that would be a great place for a link to the standard) and then to additional say that marlin also has some additional comments. That would help User2.

I assume that the standard will say that additional commands may be implemented by the firmwares and will have links to the compatible firmwares. That solves user3.

Again the proposed group has no authority to force anybody to anything. So if you want to add a full documentation to the Marlin Wiki then do it. Nobody can hold you back.

But several people have now voiced that having one central standard is much better than several distributed copies that all have small differences. The Idea is to make it easier for all users of the Interface to use this interface. Please acknowledge that Marlin is not the only firmware that offers the G-Code interface.

[thinkyhead]

Marlin wiki is just meant to document Marlin. It should include documentation on its G-code implementation too. I don't know why anyone thinks it's trying to be "authoritative" about anything.

What makes BQ own G-Code? I'm glad there is a RepRapCode, and of course I would want to contribute to such a site, but from this conversation it seems like RepRapCode now has a sense of entitlement to be the one place for this documentation.

If we're being communal, shouldn't we all be aiming to put up better documentation on reprap wiki?

That's why I'm glad to be doing the Marlin documentation in MediaWiki, because I plan to integrate it with reprap.org. I mean, I certainly had never heard of this new privately funded site that is now the central hub for g-code until this thread, and my first reaction was to look over the page to see if it had ads...

[Wurstnase]

Also, should we put then a link for every gcode which is implemented in Marlin? "G1 is a move look there link how it works". Not really user friendly...

Again, the standard is a cookbook, not a manual.

It's like a norm. If you buy a bolt in M5 and you need it's dimension, you don't get a link to look anywhere...

[thinkyhead]

@Wurstnase We used to have G-Code docs in markdown format, and of course we document the G-Code in source comments. But obviously for our convenience it's nice to have it all laid out in a wiki. In the G-Code pages I am working on, we link to other codes by reference within the same wiki. And when we mention a Marlin configuration option that is related to a G-Code, we link to that in the wiki too, connecting our configuration options with the codes. And, then we have sections discussing high-level concepts such as bed leveling compensation and delta kinematics, and we link related codes and configuration options to those concept pages. It's the same documentation we have already been doing, but in a form that is more useful. And by using both hypertext and a network address, we are taking full advantage of Internet technology to facilitate collaboration. It's just par for the course, and the right way to do documentation in 2015.

[thinkyhead]

Seems a lot of confusion could have been avoided had I just named the page "G-Code" instead of "Marlin G-Code" but for SEO perhaps "G-Code in Marlin." I think somehow it was inferred from the title that we were trying to define our own standard.

[Jnesselr]

@thinkyhead BQ doesn't own gcode and you know it. @foosel is working on this because it needs to be done and because it's causing frustration to other people as well as herself. Heck, I'm frustrated by it with BotQueue. Many bots don't even give a temperature with BotQueue because there's like15 different ways that a temperature can be presented to you depending on what it's doing.

@Wurstnase No, no, this isn't a cookbook. A cookbook is like "Oh, yeah, you can do this and this and oh look a cute little animal on the cover". This isn't a manual either. It's a standard. By that I mean, when the standard is finished, then the hope is people will code to be compliant with it so we can stop having these issues with different firmwares presenting different interfaces for the same thing.

You know, when I first started talking to @foosel about this idea, I knew we were going to have some major resistance with people not wanting to implement it. I never expected it to be this bad. Do you want 3D printers to improve? Do you really? Because honestly, there are things like this that we need to work together on and not fight over. Reading through this issue and #2028, it's obvious that there are a couple of major concerns. I'd like to address these concerns and confusions.

1) (\W+) group will own the gcode format: No one group owns the format, it's a format. I know many people have no idea who I am, but let me be clear. I want this to succeed. It needs to succeed. Having it 'owned' by any particular group is useless. Having it able to be modified by anyone is also useless. What I'd like to do is use the wiki for now, because it gives us a platform for discussion and documented per page changes. I'd rather only a few people have access to this, because I'm afraid there will be more issues with handling users that are actively working against any sort of consensus. It would be like if @thinkyhead decided that the way he wanted the command was the only way to do it, and didn't change it back when he found out how it was supposed to work. We're trying to be very careful to include all use cases that we can, and we definitely want your help doing it. I don't like the idea of calling anything a 'consortium' or anything like that, but it's just a name to me. That's all that matters.

2) This document would only be like guidelines: Oh yeah, sure, guidelines. Well, sorta. If there's a problem and it shows up in the host's software but really it's a firmware issue, then we have a problem. If the firmware says it complies with the standard but it doesn't, then that's a bug report. If it says it's loosely following along with the spirit of the standard, then that's not very useful at all.

3) Everyone hates @thinkyhead: Simply not true, I think he's caught in the middle of a misunderstanding. I have a sense of humor, just not in certain areas. I apologize that I was getting frustrated with you. I understand your intentions with documenting Marlin. I hope that you'll help with making Marlin standard compliant as well as helping out in making said standard.

4) Why have 3 different places for documentation? That's actually something we'd like to try and avoid. If the Marlin team is willing to move forward with compliance, then it would seem that the end result would be "yes, we support this command and it's standard compliant". I don't really see any issue there, do you @thinkyhead? As for the reprap.org gcode page, well... yeah it's not very useful at the moment. I would like a document that lists all of the commands on one page, but as has been pointed out, that's completely possible.

Any more issues I missed? I think we all want similar things, we're just arguing over how to go about it and what the end goal really is.