Marlin: New Documentation

[jbrazio]

Continuing the discussion which went a bit off-topic at #3063.

Wikis are basically garbage, the effort required to make one look good and easy to navigate is not productive because in the end of the day users will not update them, they are over complicated. After been told by @thinkyhead what happened in the past and due to the good experience we have in overall with Github I decided to build a mock up based on Jekyll and Github Pages.

1. All documentation is stored on Github
2. The repository is property of the MarlinFirmware Github organization
3. Everyone can fork and contribute in a standard manner like they already do to Marlin and MarlinDev
4. We can use our own domains which means the previous idea can have continuity
5. Documentation can be build either in html or in markdown

The mock up I've build can be found at jbrazio/MarlinDocumentation and it can be live previewed here.

I'm demoing the following concepts:

1. Intro page with key Marlin features
2. Quick start guides - shall be guide a newb user from start to finish to have Marlin up and running
3. Documentation - Where the current "wiki" will go

Only three links works currently:

• "Learn more" which goes to a intro page
• "Rich G-Code Support > View details" which goes into the G-Code listing
• "Documentation" which generates a list of pages under the "docs" category

Please have a look and let's take this as a starting point to build something great.

[thinkyhead]

That looks great. Let's do this thing!

[jbrazio]

Great ! I'm proceeding with it.

[elijahsgh]

How do I contribute to this?
On a cursory look I only see a proof-of-concept link. Will there be a MarlinDocumentation repository?

[jbrazio]

I've been building a proof of concept which I believe it's now almost functional, the only missing piece for me is custom java script markdown tags so we can have consistent look on attention callouts and such.

If you want to help, you may fork my repo for now and start migrating the Marlin wiki-markup to markdown inside the articles folder.

We also need a README.md file explaining how to get started with Jekyll and well.. contributing. :-)
I hope to have most of this sorted out during the next weekend.

[jbrazio]

@thinkyhead It is also important that somehow we "block" pages that were already migrated otherwise It's hard to have both systems in sync. Does Github allow locking a specific wiki page ?

[elijahsgh]

Let's get this thing wired up proper so it can start receiving contributions. Marlin/MarlinDocumentation repo maybe soon?

Worrying about locking pages is just going to be a delay or cause a future delay.

[Blue-Marlin]

It's a wiki!
Joust add: "Don't change right now! Porting."
And when done. "Ported to [link]"

[elijahsgh]

Any update?

Marlinfirmware/MarlinDocumentation sounds like a decent place to spend a Sunday evening.

[jbrazio]

Why wait for Sunday ?.. Nothing stops you from forking my repo right now and start working on it. ;-)

[elijahsgh]

Get the official project space pushed forward to enable contributors to begin adding their value to the project in a meaningful capacity.

If you don't understand the risk and you do not value or respect your contributors enough to know why they may not want to fire contributions into a potential black hole upstream independent of the project........ I can't even finish this without twitching in pain.

Again, I've taken 15 steps forward here so meet me near-ish the middle, yea?

[jbrazio]

We have now a glorious README.md.

[elijahsgh]

:+1:

[jbrazio]

@thinkyhead @AnHardt @Roxy-3DPrintBoard who is controlling marlinfirmware.org ? It was renewed yesterday.

Updated Date: 2016-03-13T01:21:19Z
Creation Date: 2015-03-12T15:12:01Z
Registry Expiry Date: 2017-03-12T15:12:01Z

[AnHardt]

Yes. I also tried to grab it. I did not talk about that to avoid a race. But it was simply continued for an other year.
The owner was/is @scotty1024 (https://github.com/MarlinFirmware/Marlin/issues/1592#issuecomment-78489661 and following messages), but he does not respond since last summer.

If you are interested you can use 'Marlin-Firmware.org'.
Currently there are some redirections:
marlin-firmware.org -> http://github.com/MarlinFirmware/Marlin
*.marlin-firmware.org -> http://github.com/MarlinFirmware/Marlin
wiki.marlin-firmware.org -> http://github.com/MarlinFirmware/Marlin/wiki

If you want some other redirections - ask for it.
Even mail redirections are possible.
No web space, no databases, no pop or imap accounts - just redirections

Sorry. No other administrative account for you. (Otherwise you could change all my other domains.)

EDITED

[jbrazio]

Thanks ! No need for admin stuff, just set and forget a CNAME record. I'm in mobile right now, so will get back to you later on today if you don't mind.

[AnHardt]

The new docu is looking great to me.
There is just one point iritating me. The font. Numbers do look very _uneven_. "G92" is more looking like "Gg2"

[AnHardt]

@Roxy-3DPrintBoard
If we want it, i suppose, you (the owner) has to transfer the example repository to MarlinFirmware

[AnHardt]

Ahh, sorry, not exactly.
https://help.github.com/articles/transferring-a-repository/

[jbrazio]

Transferring from a user to an organization
Users must have admin or owner rights within the receiving organization before they can transfer a repository that they individually own. If the user does not already have this level of access, a temporary admin team can be created with only the user. The user sending the repository is the only one who can perform the transfer.

[Roxy-3D]

If we are ready to move it... Just tell me to do it. One thing not mentioned in this quote is another possibility:

Transferring from a user to an organization:
Users must have admin or owner rights within the receiving organization before they can transfer a repository that they individually own. If the user does not already have this level of access, a temporary admin team can be created with only the user. The user sending the repository is the only one who can perform the transfer.

We can create a temporary (never to be used again) user account that both the receiving side and the original side have admin rights to. Instead of doing the transfer in one step, we do it in two steps.

[jbrazio]

As last resort I believe it can be transferred to someone inside the org with enough rights (user to user) and then from that user account to org.

[Roxy-3D]

When there is consensus I'll do what ever it takes to make it happen. But you will probably have to give me 3 or 4 easy to understand steps that happen in order.

Just for my benefit, can we have a quick discussion about the merits of doing Push Requests on the documentation? If the documentation is it's own repository (within the MarlinFirmware organization) we should be able to give the Documentation team leaders authority to approve Push Requests against it. Does that handle everybody's concerns and needs?

[elijahsgh]

@Roxy-3DPrintBoard I thought we had consensus about 5 times over? Even @thinkyhead seemed to greenlight it above.

Step 1) Clone the repo.
Step 2) Create a new repository.
Step 3) Point the cloned repo to the repository upstream (follow the instructions github gives you and just edit .git/config and update the URLs)
Step 4) Push

The downside to the github wikis are that whole pages have to be edited. The upside to things like Jekyll is that we can manage it exactly like a git repository - merge, pull, clone, PR, etc.

Let's go!

[jbrazio]

@Roxy-3DPrintBoard This new documentation system is not a wiki, the concept is everyone can contribute but someone must curate it, in fact Travis is even doing validation if everything is being build as it supposed to be.

Then there are two steps, one is the process of including new contributions on the master branch; the second one is to rebase gh-pages from master which only then will introduce the changes live on the website.

@tamarintech what we had reached is that when we find it is ready it will be transferred up to then it stays where it is right now, the location of the $%&"! thing does not block anything.

[Roxy-3D]

@Roxy-3DPrintBoard I thought we had consensus about 5 times over? Even @thinkyhead seemed to greenlight it above.

@tamarintech what we had reached is that when we find it is ready it will be transferred up to then it stays where it is right now, the location of the $%&"! thing does not block anything.

We have consensus that we need better documentation and we need to update it. The actual details about where is lives, and how it operates is still evolving.

[elijahsgh]

@jbrazio Am I supposed to interpret that as it's not being moved..... out of spite or....?

Let's go!

[Roxy-3D]

I think the way to interpret that is progress can be made with the current location. (Step 3 up above is probably obvious to you. But I need some sub-bullet points to be successful with that part of the transfer.)

There is no spite here. We are working together to get a well thought out plan in place for better documentation. Ideally, that documentation will have a way for it to stay accurate and reflect the release it is associated with. It would be real nice if the documentation had a way to automatically generate a 'Differences Report' between two versions. This is not trivial discussion to get right.

There are also other perspectives. Do we want to organize the documentation by skill level? (Probably not. But I'm just trying to add some color to the discussion.) If we did do that, what are the Plus's and Minus's ? How much should we focus on getting a new printer configured properly? Would we be better off organizing the obvious and simple commands that a beginner needs to know and use? The questions go on and on. And how we answer those questions affect how the documentation evolves and what it takes to keep it alive and growing.

I really don't know the answer to these questions.

[elijahsgh]

When we push the Jekyll bases docs you will see the normal github opportunity to compare changes. We can also work branches side-by-side with upcoming releases and launch them into the appropriate branch for automatic github publishing at release. This is a great opportunity to present modern documentation with a better workflow than the github wikis.

There is no reason to sleep on this. Push a new repo with jbrazio's PoC and let's get started. If you don't like it then we can scrap it. Normal users won't even see it since they'll most likely end up on the wiki instead.

[jbrazio]

I'm not a member of core team, I just step up to respond to a demand, I will continue my work on this repo until someone from core team asks me to migrate it. It's clear that my effort is being backed up by core team members so if you want to help just start making PR against my repo as that's the place it's gonna stay until all the Marlin core members decide where to place it. If you are not ok with this then please step aside. You show a lot of motivation but so far anything has come out of there other than trying to rush stuff that is not important for now. The repo will be migrated to the place the core team decides and when the core team decide.

[elijahsgh]

Did a non-core team member seriously just tell someone to bugger off? o.O Did that seriously just happen? I'm going to pretend like it didn't because that would be absolutely preposterous.

@thinkyhead said the best way to contribute was documentation and using Jekyll, a feature of github for a few years now, seemed to be backed by a core team member. Getting a very common product integration working with this repository is a great way to get the documentation up to date.

Let's go.

[jbrazio]

@tamarintech you have serious difficulties dealing with opinions different from yours.

[elijahsgh]

Less troll, more repos.

[elijahsgh]

@Roxy-3DPrintBoard The third step extrapolated:

On github, click New Repository. Create the new repository (ie: MarlinDocumentation)

Git will present you with a screen that has an option reading "...or push an existing repository [...]" This is what we'll be doing. You can verify the commands shown in that section with the commands a few steps below.

Clone https://github.com/jbrazio/MarlinDocumentation

Navigate to the directory on your computer.

Use the following commands to push the repo to the new repository you created (update the URL below as required):

git remote rm origin
git remote add origin https://github.com/MarlinFirmware/MarlinDocumentation.git
git push -u origin master

You should see jbrazio's Proof of Concept appear in the MarlinFirmware/MarlinDocumentation repo. This only clones the master branch and it would be ideal if you created a Dev/Development/whatever you'd like us to start contributing to. When you're ready, you can create a gh-pages and finish the Jekyll integration by setting up the Github Pages and editing _config.yml.

[jbrazio]

that documentation will have a way for it to stay accurate and reflect the release

In fact this new "page" should not only be a documentation repository but also a place where people can have a clear view:

• What is the current stable Marlin release
• Where can I get the current stable release
• How can I flash my board with the current stable release
• What features have been incorporated in the latest release
• Download of hex files (at the beginning maybe only for the supported example configuration -- I believe I can hack a bit Travis to work for us, just have to test it)
• Have a home for the online configurator by @thinkyhead
• etc etc

This means not everyone should be doing changes like a wiki, a team of curators shall be defined.
In order to handle (and keep track) the PR method seems to be the best solution, like this multiple things can be happening at the same time without interfering.

Right now the effort I believe should be into transfer the existing documentation from the wiki, no matter how outdated it is.

Next the existing documentation must be polished and brought up to date with the latest RC version (question open).

Then it comes organization, I do agree we should have documentation per version @Roxy-3DPrintBoard you're right, we have to take this into account during the polish phase.

[elijahsgh]

This is all more brakepads and subterfuge. Have any of you used Jekyll or Github pages? Not trying to be anywhere near as pedantic as other people and it's a serious question.

GitHub Pages are repositories that provide content for static sites hosted at github via a git repository.
git features branches and tags.
Jekyll is a tool for generating static content.
The three together provide a repository that tracks static content with a special branch served as a webpage from GitHub.

When 'launched', we would find the documentation at marlinfirmware.github.io/MarlinDocumentation and it's going to serve us whatever Jekyll has built. The repository itself can contain tags for specific versions and, since these pages are static content, you could simply let the user download the _manual specific to their version_ as HTML.

Curators and other nonsense above is literally the antithesis of github or any of the tools in this workflow. Contributors fire off pull requests, repository owners review, the changes are merged, and the decision is made to tag release versions as necessary or merge to the special branch used to publish pages.

If the whole thing dies in a fire, as @jbrazio is continuously trying to guide it to, then you can simply replace the index with a redirect to the current release's wiki.

[Roxy-3D]

If the whole thing dies in a fire, as @jbrazio is continuously trying to guide it to, then you can simply replace the index with a redirect to the current release's wiki.

@jbrazio is doing nothing of the kind. Let's talk about code for a moment. The 'normal' work flow is the new code is worked on and debugged in the developer's account. This makes sense because the developer needs full control and until the code is debugged and working enough it usually doesn't make sense to fold it back into the up stream branch.

My impression of what @jbrazio is suggesting (and doing) is the same thing except aimed at documentation.

[elijahsgh]

@jbrazio is doing nothing of the kind. Let's talk about code for a moment. The 'normal' work flow is the new code is worked on and debugged in the developer's account.

You missed the part where he took it upon himself to tell contributors to bugger off? Also the whole bit about "documentation per version" which, as I've explained, is something you _get for free_ when using GitHub Pages with Jekyll.

GitHub Pages and Jekyll _lend themselves to working docs just like you work code_ which is miles beyond what the wiki offers. This was never in question, at least for anyone that's done this before, but now we're supposed to discuss documentation per version? Seriously, have you all ever used any of this before (sounds snarky, but really isn't meant to be)?

Let's go already. You all can learn how this works as you do it instead of picking out semantics that don't even relate.

[jbrazio]

My impression of what @jbrazio is suggesting (and doing) is the same thing except aimed at documentation.

Exactly.
The workflow we have for RC/RCBugfix is working perfectly for this project, I believe we should use the same exact workflow but for documentation.

[elijahsgh]

dev
gh-pages

All PRs go to dev, dev gets merged to gh-pages....
Tag the versions for doc releases.....

Do you want me to find a public project that does this already for your reference?

Can we just do this thing already?

[jbrazio]

@AnHardt can you check if you like better this font ? The weird looking numbers are gone, that's a characteristic of Georgia font which was being used.

[AnHardt]

@jbrazio
I like it.

[elijahsgh]

@Roxy-3DPrintBoard I don't see the MarlinDocumentation repo. Did you need any more assistance with creating it?

[thinkyhead]

Lots of good ideas flowing back and forth, in spite of the sniping. I like it.

Only a few things are important to me concerning the documentation.

• It should be editable through Github as part of the MarlinFirmware repo.
• It should be easy to read and well-organized.
• It should include images where words may be confusing.

I'm also thinking that we should produce some videos (on YouTube) going through the process of configuration, calibrating E-steps, troubleshooting, etc. Video can be so much clearer than the written word sometimes.

[elijahsgh]

MarlinFirmware isn't a repo - it's an org. As it exists now, it would live at MarlinFirmware/MarlinDocumentation or http://marlinfirmware.github.io/MarlinDocumentation

If you really wanted to you could put it in the main Marlin repository, but this would be very cluttery with all of the assets.

We can link images, embed youtube videos, or even add rich media directly to the repository. Again, since Jekyll produces static content, this can actually be downloaded as HTML and browsed offline. If you're OK with having video content directly in the repository then there's no reason that can't be offline viewable, either. We can work towards all of that.

..... but first someone needs to make the actual repository.

[Roxy-3D]

@thinkyhead It is your call how we proceed. Can you make the repository? If not, and you want it done, I'll try to do it in the morning.

[jbrazio]

Latest changes:

• @AnHardt changed the font again to one, IMO, more readable when there is a lot of text together.
• Striked out the links which are not yet working.
• Organized the sections a bit more, added some external links to important project zones (repos, bugtracker etc).

link

[Roxy-3D]

@thinkyhead You have mail...

[elijahsgh]

Any updates?

[paulusjacobus]

Hilarious @tamarin . I love the new layout, hopefully is up and running
soon. Happy to contribute in refining the content (content is King)

On 16 March 2016 at 05:57, tamarin [email protected] wrote:

Any updates?

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub
https://github.com/MarlinFirmware/Marlin/issues/3088#issuecomment-196972454

[elijahsgh]

@roxy-3dprintboard

Can you make the repository? If not, and you want it done, I'll try to do it in the morning.

Did you mean _this morning_ and not yesterday?

[Roxy-3D]

I'm still waiting to hear back from ThinkyHead on how he wants to proceed. He knows much more about the requirements for good documentation than I do. My guess is ThinkyHead is still thinking about how he wants things organized. (Not to mention, he has been _VERY_ busy trying to get RCBugFix polished up)

But none of that matters with regard to what you are trying to accomplish. @jbrazio has said he will merge Pull Requests with improved content into his repository to keep things coordinated and moving forward.

[elijahsgh]

@thinkyhead appears to have greenlighted this at least twice. The docs will evolve as content is added - I absolutely promise you. Curators, planning new ways to complicate _very well established workflows_, and rigid expectations of a system it seems few are familiar with are velocity killers that will land you in stagnation.

I am not contributing to a third party project in order to contribute to this. There is absolutely no reason to build out _a separate product_. Clone it and push it up - I left step-by-step instructions. If you hate it later then delete it. No risk.

The hesitation here is unwarranted and I can't keep from interpreting it as just spiteful when the replies of "step aside - we don't want anyone's help" and "I'll do this in the morning - I mean indefinitely delayed" are piling into excuses.

In the words of @thinkyhead -
Let's do this.

[Roxy-3D]

I am not contributing to a third party project in order to contribute to this.

Thank you for your contributions on this topic. If you change your mind, I'm sure @jbrazio will carefully consider any Pull Requests you make against his work.

[elijahsgh]

Thank you for your contributions on this topic. If you change your mind, I'm sure @jbrazio will carefully consider any Pull Requests you make against his work.

Don't be daft. The amount of characters it took you to be snarky in your hesitation to actually make this project better is a significant number more than it would take you to create the repository.

[McBride36]

Why fork from @jbrazio instead of official marlin repos?

Edit: especially when you ask others to contribute to the documentation. why would they fork from him instead of an official source?

[jbrazio]

step aside - we don't want anyone's help

@tamarintech you are a programmer right ?
If you read again my sentence there is a very specific if-then condition for the "step aside". All contributions are really needed and very welcome, specially the ones coming from such a motivated person as you.

If for some reason or planet alignment you don't feel right contributing documentation to the repo which is [temporary] under my account, you may do it under the official repo at the wiki space, as long as you do not edit articles which have DNE at the name and/or "Do not edit" somewhere in the body and do the contributions using Markdown instead of Mediawiki formatting, they will be merged without issues.

[Roxy-3D]

Long term, the documentation would obviously be part of the Marlin Firmware Repositories. But everybody is busy and we don't have all the answers on how we want to organize and support the documentation. We will get those issues resolved soon enough.

But in the mean time, there is a very viable path forward where progress can be made. We most certainly will review and absorb the work going on. And probably we will be giving Administrator rights to the big contributors of the documentation so they can keep moving it forward. You know what? Given the fact some individuals will end up with Administrator privileges, this is actually the Correct way to proceed because right now we are getting a first hand look at who is a team player and who likes to bully people.

[McBride36]

If for some reason or planet alignment you don't feel right contributing documentation to the repo which is [temporary] under my account
Long term, the documentation would obviously be part of the Marlin Firmware Repositories.

Then why not get this part started now? More people will benefit.

[jbrazio]

a third party repository for the documentation of this project is the opposite of the right thing to do

@tamarintech this is not questionable, no one ever said this will be the final home for the documentation, please point me where this was said out loud ?

@McBride36 in @Roxy-3DPrintBoard own words:

Long term, the documentation would obviously be part of the Marlin Firmware Repositories. But everybody is busy and we don't have all the answer on how we want to organize and support the documentation. We will get those issues resolved soon enough.

[thinkyhead]

Sorry not to be chiming in more on this topic. The whole imbroglio with that insufferable %$&% is precisely what I try to avoid getting pulled into, and Marlin _for some reason_ seems to be a magnet for it. I had to maintain a _noble silence_ or I would say too much! We've just been trolled. So I deleted a few of his posts. I'm tempted to delete everything irrelevant to the topic at hand —"Jefferson Bible" style— and make this thread sane again.

Anyway!

My favorite long-term option is that the documentation should live in the "Documentation" folder in the Marlin repository, as we previously had. Within that folder (i.e., "Documentation/html") should be some form of web-navigable documentation. It should be possible to navigate the documentation from your local hard drive, or a folder anywhere on the web.

As for creating the documentation, frankly any well-respected open-source methodology to produce navigable (and searchable?) documentation should be considered. For certain portions, we may utilize the output of Doxygen-style comments in the sources. For writing about the more in-depth topics, we can use the Github wiki. Heck, maybe we can use my crufty wiki at http://wiki.thinkyhead.com/ :blush:

The Github Marlin Wiki

Right now the Github wiki is the most convenient place to develop Markdown and link up topics. Did you know you can check out the Marlin wiki as a Git repository? It's a great way to work on it.

Jekyll

I hope that Jekyll (or whatever tool we settle upon) can work with the Markdown from the Github wiki, mainly so it can preserve any wiki links, and I hope it's very easy to edit.

I'm not personally familiar with Jekyll, so I can't vouch for its advantages over all others. To reiterate our essential needs:

• There should be a straightforward way to edit the documentation.
• All documentation should live within the main Marlin repository (as much for the URL as anything).
• There should be some "automated" way to generate the static content from the raw content, so it stays pretty up-to-date. Weekly, if not daily.

Github can host a website – sort of

In case you're not familiar with it, the domain rawgit.com provides a way to turn any web-hostable Github content into … web-hosted content. Using rawgit.com in conjunction with a URL-forwarder, you can have the documentation appear as if it lived at "marlinfw.org/manual" for example.

Here's an example of rawgit.com link, to one of my repositories:

http://rawgit.com/thinkyhead/MarlinConfigurator/master/src/index.html

Why not reprap.org?

Another option to seriously consider is to host (or at least mirror) documentation at the URL "reprap.org/Marlin/..." — a pretty decent Mediawiki site which is probably not going away soon. Hosting on reprap.org would also demonstrate a spirit of solidarity with the community. In that respect, one project that gets kudos for their excellent documentation is Project Clone Wars out of Spain. Have a look at their pages: http://www.reprap.org/wiki/Proyecto_Clone_Wars … and their Google Search result looks pretty nice.

Domain Sponsorship

I personally like marlinfw.org as a domain. But to maintain a domain in an open source project is not always simple. The keys for the domain will need to be shared among at least two individuals at any time. Pass nothing around without using at least GPG encryption. All that kind of thing, to make sure it can't fall into the abyss.

Hosting or just forwarding?

Should there be hosting for the domain or just forwarding? Complex forwarding basically requires the same infrastructure as hosting, but some companies offer DNS services, which may be enough. I actually part-own a Hostgator hosting account, so I can create an unlimited number of websites and set any bandwidth or storage limits that I want. The domain would only need to be pointed at my custom DNS servers there.

If we opt for just forwarding, all static content can be accessible by forwarding/rewriting to rawgit.com, making the documentation appear to be hosted from marlinfw.org/docs (for example).

What are the pros and cons of these ideas? What other options are worth looking at? What are the important considerations going forward, to make sure the documentation is most useful? Should it matter if we can generate a PDF version? (That would be kind of nice.) What questions am I forgetting?

[jbrazio]

A lot of food for thought there.. :-)
Let met try to tackle some of them.

IMHO Marlin needs three things right now:

1. Updated documentation
2. A central place to access "everything Marlin"
3. Be less technical and more user friendly

I hate wikis.. I hate the way wikis work, I hate the way wikis look, I hate the workflow wikis provide.. they are crap. The only good thing about wikis is that any one can contribute to them (so we shall keep this feature).

Having said that it's clear why I'm trying to propose a solution out of the wiki ecosystem, and here is where Jekyll comes in, Jekyll is the preferred method for Github to generate static pages, in fact Jekyll is part of the Github framework and any project can take advantage of it to host their own website, this feature is branded Github Pages.

A Jekyll website consists of some source code and a toolchain which generates the static html files from the src. Github pages automatically builds the static content if the project has a gh-pages branch with the Jekyll src in it. -- This is the method I'm using at the PoC.

Jekyll uses Github Markdown, the same Markdown language we are used to use on the comment system inside Github. Github wiki on the other hand uses MediaWiki Markdown language so most of the pages I've been moving into the PoC system had to be converted from Mediawiki to Github markdown (there are automatic tools for this like pandoc).

Github even allows custom domains, as an example http://test.marlinfw.org/ is being hosted from my PoC repo, everything is inside Github.

Sidenote: I've secured the domain marlinfw.org and I've sponsored it for one year, when required/decided please provide me the account to which I shall transfer the ownership of the domain. Currently the registar is hover.com and DNS servers are linode.com.

To sum up the advantages I find about Jekyll that makes me propose it as the best solution for Marlin:

• Static content
• Repository based
• Articles are written in Github Markdown
• Integrated deeply with Github due to Github Pages
• Zero additional infrastructure needed (just a DNS CNAME)
• It's not a wiki. :-)

Every open source project must have a website so beside the work that must be done concerning documentation, Marlin could use the domain marlinfw.org as the central point to access the Marlin ecosystem. What I mean is a place where a user can go and have links to all the Marlin related repos, as well as guides, developer guides, pre-build binary files, web-based configuration generator, up to date news, etc.. IMHO this will make Marlin more [new] user friendly thus this tackles point 2 and 3.

But this also highlights another wiki fundamental issue, marlinfw.org to be an official project website must be somehow curated by the team, in the same context as the C++ source code is curated by a team. Using wikis you must build fancy permissions systems, user based authorizations, lock pages and who knows what in order to have such control over the overall quality and look of the website, it's feasible but not optimal.

With Jekyll/Github there is no distinction on the workflow between curating the C++ src code or the website src code, all is done using the Git Pull Request workflow.

IMHO I do believe that a specific MarlinDocumentation should be created inside the MarlinFirmware organization, this will make a clear distinction between PR that are related with documentation and PR which are related with Marlin source code.

This does not invalidate (as everything will be inside Github) to tell Jekyll to update trough a hook the MarlinFirmware/Marlin/Documentation with the latest static bundle for offline viewing; but if we plan to provide any sort of offline documentation with the Marlin source code I would prefer for it to be in .pdf.

Doxygen would be my next push.. if you look at my PR #3113 I already documented the changes using Doxygen so I'm really glad you brought that topic out.

[AnHardt]

@jbrazio

Github wiki on the other hand uses MediaWiki Markdown language so most of the pages

The Github wiki perfectly understands Github Markdown (it's the default).
Having so many pages in MediaWiki Markdown is a result of rescuing the content from MarlinFirmware.org (MediaWiki) to the Github wiki. As Github wiki allowed me to just paste in the MediaWiki Markdowned content when the 'Edit mode:' was set accordingly, this was the chance to do it in one night.

I love wikis. No other documentation system sets the hurdle to contribute so low. Everyone can improve the content at anytime. Sadly too few people take that opportunity. Even people involved in this thread do not realize the possibilities. Everyone who wants somebody else to change wiki-content for him/her did not got the concept. If there is anything you want to improve - just do it - now.

On the other hand, making your first PR to Github repository needs more than a bit of knowhow.

With the Github wiki I have one major problem. I'm missing Categories (https://www.mediawiki.org/wiki/Help:Categories). They do make structuring the content so much easier. For that reason alone I'd consider moving to http://reprap.org/wiki/Marlin or another site, making a MediaWiki possible. Also the chance to get mail for every change, is a great feature to keep track of what's going on.

Content is king. Simplicity to contribute is second, Design is third.
(Says one who thinks his time is better invested in code than in documentation)

[jbrazio]

@AnHardt

Having so many pages in MediaWiki Markdown is a result of rescuing the content from MarlinFirmware.org

Ok that explains why I had to convert them.

On the other hand, making your first PR to github repository needs more than a bit of know how.

Here I must agree with you, it may be the drawback of Jekyll, wikis theoretically allow any one to contribute, "theoretically" because the technical degree required to write the missing documentation for Marlin, in a clear way, it's not a job for someone with light knowledge over the tool or the environment were the tool resides; take me for instance, I do not have enough knowledge to try to explain to someone how a DELTA kinematics work or how to correctly setup and fine tune a printer of its kind, the starting point for such a document should come from someone who did/knows the implementation inside Marlin and I'm positive this person knows how to do a PR. Then cleaning up the document or adding pretty pictures can be done by someone at the same level as I am.

On the other hand Jekyll allows categories, in fact multiple categories per article/page and by using Github pages and having a dedicated repo for MarlinDocumentation will allow you to subscribe to notifications by mail or by the Github system.. same exact workflow as the C++ src repo.

No other documentation system sets the hurdle to contribute so low. Everyone can improve the content at anytime. Sadly too few people take that opportunity.

I have been given smoothieware.org as the example documentation, they seem to base their system on Wikidoc. I'm not saying wikis do not work, they do for some projects, for Marlin.. well it hasn't been working as well as it should so far and this is one of the reasons why I believe we should try a different approach; this doesn't mean it _will_ work, in one year from now you may be saying "FU João, this ain't working either !". :-)

Content is king. Simplicity to contribute is second, Design is third.
(Says one who thinks his time is better invested in code than in documentation)

I do agree, but the best outcome would be to have a good combination of all, even if this means we have to compromise some. The whole is greater than the sum of its parts.

[Roxy-3D]

I do not have enough knowledge to try to explain to someone how a DELTA kinematics work or how to correctly setup and fine tune a printer of it's kind, the starting point for such document should come from someone who did/knows the implementation inside Marlin and I'm positive this person knows how to do a PR..

Don't bet too heavily on this one. I'm currently writing code to do an Automatic Mesh Bed Leveling System for Delta's (that is going to Rock!!!). But every time I put Git on my machine I end up having to rebuild my disk image. When the time comes to write documentation for the Delta Automatic Mesh Bed Leveling System, it has a much higher chance of getting me to write the documentation if it is a Wiki just because I won't have to fight the tools.

One thought worth considering is this: Who do we expect to be adding to and updating the documentation? If the bulk of the content is going to be done by just a couple of people, whatever tools that can get the job done easiest and best make sense. There is the opposite bookend on that shelf: If the bulk of the content is going to come from just little bits of information entered by 1000's or 10,000's of people, then a simple web-based interface may be more suitable because there is not a large learning curve in front of them to get their contribution.

My guess is we are in the middle-ground somewhere. I don't know what the right answer is. Probably my biggest concern about a wiki is somebody can go crazy and easily destroy content. The good news is, we can revert GitHub wikis so we should be able to recover lost information.

[Blue-Marlin]

Probably my biggest concern about a Wiki is somebody can go crazy and easily destroy content.

For every wiki the last (correct) version of a page is only about 5 clicks away.

[thinkyhead]

A central place to access "everything Marlin"

I very much want this too – that marlinfw.org should be a portal to all-things-Marlin. But I also feel like it should be run by "fans of Marlin" and not as part of the formal Marlin project, simply because our previous experiences trying to have an "official" domain left us with a bad taste in our mouths. If we cannot ensure that it will always be under the control of the current custodians of Marlin, it will always seem to be "at risk." On the other hand, "fans of Marlin" are free to take the "official documentation of Marlin" which we would host in the repository (perhaps in Jekyll format, perhaps another) and host it on any domain they want. Of course this also means we wouldn't want to mention marlinfw.org in the documentation or show it on the LCD screen.

The main thing that I like about the Jekyll site is that it looks a lot more classy than a typical MediaWiki-based site. However, since it lacks a searchable back-end, doesn't offer a direct route for users to add corrections, and lacks the power of a dynamically-hosted site built on a database, for me it falls short.

I agree that the quality of a wiki largely depends on the skills and attention-to-detail of the editors. For this reason, some of us would have to take on a custodial role around any Marlin section we decided to host on reprap.org. Even though the docs would be separated from the repository, we could still track issues and assign documentation tasks through the issue queue. "Add Mesh Leveling to the Marlin wiki" might be a task for someone on an odd Tuesday.

So, I wonder if we can't make the main Marlin page on the reprap.org wiki look just as classy as the Jekyll generated page at http://test.marlinfw.org. I also have design skills, dreaming in fibonacci spirals and golden ratios, so I can help experiment with achieving a nice layout within Mediawiki. I'm guessing that it's not nearly as easy to make a pretty tabular layout within the Github wiki – but since it supports MediaWiki markup, perhaps it can. Wherever the "official docs" are hosted, we should try to make the "Home" wiki page here look as nice as possible, with clear links to the important topics.

[jbrazio]

trying to have an "official" domain left us with a bad taste in our mouths. If we cannot ensure that it will always be under the control of the current custodians of Marlin, it will always seem to be "at risk."

I do understand this, that's one reason I tried to come out with a solution more "flexible" than a plain wiki but could always be under the MarlinFirmware control by removing all the external dependencies. If Jekyll resides inside a repo owned by the core team and if all Jekyll based documentation is forced to be written in Markup then if something goes wrong core teams always have the hot-knife in one hand and the butter on the other, being the only pending point the domain name, but also this is easily fixable by transferring the ownership to the core team as I already proposed to do.

As an update, this is the current look and feel after my last submissions:

Article link: http://test.marlinfw.org/articles/getting-started/configure.html
Category link: http://test.marlinfw.org/articles/getting-started/

[Roxy-3D]

I like the way the left hand topics list changes how it is high lighted as you scroll down the page. It would be really cool if the high lighted topic could automatically expand and show its bullet points indented underneath it.

This really does look pleasing and professional. Can we talk about how hard it is for a random person with no experience with these tools to go in and expand a topic area and have it pretty much work? Suppose in that screen shot up above I wanted to add some extra information or constraints to the Power Supply types. I want to add 3 = Fuel Cell. Am I going to be able to find that in the files easily? Can I make the changes without causing everything to break?

[jbrazio]

It's indeed doable, I'll try to hack something about it on Sunday.

If it is the first time you're contributing, and want to do it the right way, then you must do:

git clone <repo URL>
git checkout -b new-cool-stuff

[edit the file located in articles/]

git add -A
git commit -m "Edited the article ZXY"
git push

[do PR in Github]

(People can skip the branch stuff if they want to save some keystrokes)

This allows you not only to edit articles but add new site sections, edit existing templates, move stuff around, publish news etc etc.

[thinkyhead]

I generally support anything we can host in the repo. The domain issue is something to work out, and perhaps it is not so hard to keep a domain alive and well for a while.

easily fixable by transferring the ownership to the core team

Whoever that is, this week. And that's the main issue. Marlin really doesn't have a "core team."

But the owner of the MarlinFirmware org name on Github is Erik van der Zalm. He works at Ultimaker with David Braam, the original author of Cura. Parts of Marlin early on were authored by Bernard Kubicek. I suppose if anyone should be the key holder for an "official domain" it should be Erik, because anyone else may come and go.

Anyway, I'm looking forward to editing some documentation soon! But over the next 24 hours or so, I want to get all the pieces in place to release RC4, probably reverting #3082 until we have a stronger consensus how best to disable probes when not in use. Perhaps we'll have that figured out for the next (and final) release candidate, and maybe it will be more attuned to the approach taking shape in #3065.

[jbrazio]

That gave a clear view of the Marlin roots, but for now they seem to be a bit "offline" on the project; from an outsider as I am the current active maintainers are @Roxy-3DPrintBoard, @thinkyhead, @AnHardt and @Blue-Marlin.

I was following the RC4 build up and I must admit #3082 and all the config changes it introduces really went by me unnoticed but I do agree with the principle of simplifying the concept.

I have stopped converting the existing Wiki documents to the PoC system because it's a bit uncertain for me if it will be used and I don't want to create double work by having to revert all the wiki documents to their original state. If you have a look some are now marked as DNE (Do Not Edit).

PS: I'm still owning Roxy a pretty folding TOC.

[thinkyhead]

Now that our less-rickety Marlin 1.1.0-RC4 is out to the world, it seems like an opportune time to add to the documentation and get out another build of the "test" wiki in-progress.

Speaking of documentation… On Wednesday I will be doing an informal presentation on Marlin Firmware at the Portland 3D Printing Lab monthly meetup. My outline for the presentation goes sort of like this:

• Who am I? Why am I here? How did I fall in love with plastic-squirting robots?
• A basic overview of Marlin: What it is, its illustrious history, genealogy since grbl/sprinter
• The miraculous way that Marlin develops, the Github process, evolutionary development
• A short overview of Marlin configuration (in 1.1.0 – no 1.2 "exploded configurations")
• Along the way describe the many changes to Marlin since "Marlin 1.0"
• After that, the future of Marlin (always better)
• Invite involvement in the project, and the documentation project.
• Give links of where to go for more information (here and the RepRap Forums "Marlin" section)

If a video is made, that will be good. Otherwise, I can perhaps take my slides and add audio, and put that up on YouTube later.

[Roxy-3D]

If a video is made, that will be good. Otherwise, I can perhaps take my slides and add audio, and put that up on YouTube later.

It would be really good if your presentation can be recorded and posted!

[jbrazio]

For sure it would give a jump start to the Marlin Youtube channel :-P

[jbrazio]

@thinkyhead @Roxy-3DPrintBoard @AnHardt did you had time to discuss if we should proceed with my suggestion and the current PoC repo be migrated to MarlinFirmware/MarlinDocumentation thus using the domain marlinfw.org as the official "concentrator" website ?

[thinkyhead]

good if your presentation can be recorded

@Roxy-3DPrintBoard Hopefully good! I'm trying to narrow it down so it isn't too geeky.

discuss if we should proceed with my suggestion

@jbrazio I guess we should discuss that here. I have no objection to migrating it into a new project under MarlinFirmware. Seems like the right thing to do, and then keep going forward with it in tandem with the rest of the repos.

[Roxy-3D]

I think the idea of migrating all of the documentation to MarlinFirmware/MarlinDocumentation makes sense.

I need some help to understand how using the marlinfw.org as an "Official Concentrator" helps things. It would seem everything can be done within MarlinFirmware/MarlinDocumentation.

[thinkyhead]

There may be some other hosting options to consider… This one comes up near the top of my web searches: http://www.simplybuilt.com/explore/free-websites-for-open-source-projects

There may be other advice worth considering also.

[jbrazio]

There may be some other hosting options to consider

I guess we could do it.. but starting with Git pages will allow us to start lean, fast and scale out to another hosting platform when [and if] required.

I need some help to understand how using the marlinfw.org as an "Official Concentrator" helps things. It would seem everything can be done within MarlinFirmware/MarlinDocumentation.

You can access a Git hub page by two ways:

• the native URL which for the PoC is http://jbrazio.github.io/MarlinDocumentation
• a custom domain, which for the PoC is http://test.marlinfw.org

But both ways are served exactly from the same source repository.
@Roxy-3DPrintBoard this this answered your concerns or did I miss the point ?

[Roxy-3D]

But both ways are served exactly from the same source repository. @Roxy-3DPrintBoard this this answered your concerns or did I miss the point ?

I guess I misunderstood. I got confused and thought we were talking about an "Official Concentrator" web site that was not on GitHub as the only way to get to the documentation. It feels more natural to me that everything be on GitHub but that is based on what I know and understand right now.

Are we ready to create a 'Documentation' project within MarlinFirmware?

[jbrazio]

For me we can proceed, just tell me to whom I transfer the existing one for importing.

[Roxy-3D]

For me we can proceed, just tell me to whom I transfer the existing one for importing.

Are we ready to create a 'Documentation' project under MarlinFirmware? If we are ready to move content there, we just need agreement that makes sense to do.

[jbrazio]

I'm closing this issue as the new Documentation Project repository has been created.
Have a look at MarlinFirmware/MarlinDocumentation.

[fontanares]

Hello!
My english is poor and
I can hardly time to translate it . Can someone send me or tell me where to find the configuration manuel Marlin?
In particular I look for the parameters " EXTRUDER_RUNOUT " .
Thank you.

my mail is: [email protected]

[thinkyhead]

We don't have a manual yet. Here's what I can tell you. First, the configuration file gives a reasonable explanation…

//  extruder run-out prevention.
//if the machine is idle, and the temperature over MINTEMP, every couple of SECONDS some filament is extruded
//#define EXTRUDER_RUNOUT_PREVENT
#define EXTRUDER_RUNOUT_MINTEMP 190
#define EXTRUDER_RUNOUT_SECONDS 30
#define EXTRUDER_RUNOUT_ESTEPS 14   // mm filament
#define EXTRUDER_RUNOUT_SPEED 1500  // extrusion speed
#define EXTRUDER_RUNOUT_EXTRUDE 100

Note that the comment on EXTRUDER_RUNOUT_ESTEPS is nonsense. It does not specify millimeters.

Here's what the code is actually doing with these values…

planner.buffer_line(destination[X_AXIS], destination[Y_AXIS], destination[Z_AXIS],
                 destination[E_AXIS] + (EXTRUDER_RUNOUT_EXTRUDE) * (EXTRUDER_RUNOUT_ESTEPS) * planner.steps_to_mm[E_AXIS],
                 MMM_TO_MMS(EXTRUDER_RUNOUT_SPEED) * (EXTRUDER_RUNOUT_ESTEPS) * planner.steps_to_mm[E_AXIS], active_extruder);

For the default settings, when the temperature is over 190, every 30 seconds the extruder will move 14 * 100 "steps" at a rate of 1500mm/m. The actual length in millimeters will depend on your extruder's STEPS_PER_UNIT setting.

I hope that makes sense.

(I'm certainly going to patch this feature before 1.1.0 is released so that we can simply specify millimeters instead.)