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 notifications@github.com 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?