Tutorials here?

[BurdetteLamar]

At RubyConf, we discussed having tutorials (and other user-friendly doc) here at https://github.com/sparklemotion/nokogiri, instead of at https://github.com/sparklemotion/nokogiri.org/, as now.

Is this something we should move forward with? Is there any loss in doing so? (I seem to recall that on nokogiri.org there's some sort of searching support; anything else?)

[flavorjones]

@BurdetteLamar Thanks for thinking about this! Yes, my ultimate goal is to have all of the nokogiri.org content in this repository, and generate a static site that doesn't need mkdocs.

The only tricky thing to consider about the tutorials is that they are "executable documentation" and need to be "compiled". If you check out the https://github.com/sparklemotion/nokogiri.org repository and look at docs/tutorials/searching_a_xml_html_document.md you'll see:

# Searching an HTML / XML Document

## Basic Searching

Let's suppose you have the following document:

~~~ inline assets/shows.xml

Let's further suppose that you want a list of all the characters in
all the shows in this document.

~~~ ruby assets/search-setup.rb assets/search-xpath-characters.rb

The `Node` methods `xpath` and `css` actually return a [NodeSet][],
which acts very much like an array, and contains matching nodes from
the document.

...

Those ~~~ lines tell a preprocessor to include the file (and, if it's ruby, execute the file). So if you run bundle exec rake tutorials:generate you'll see something like this:

writing to staging/tutorials/searching_a_xml_html_document.md from docs/tutorials/searching_a_xml_html_document.md
  inline file: assets/shows.xml
  inline file: assets/parts.xml
  inline file: assets/atom.xml
  ruby file: assets/search-setup.rb
  ruby file: assets/search-xpath-characters.rb
  ruby file: assets/search-xpath-characters-first.rb
  ruby file: assets/search-xpath-characters-drama.rb
  ruby file: assets/search-css-name-sitcoms.rb
  ruby file: assets/search-single-results.rb
  ruby file: assets/search-xpath-namespace-verbose.rb
  ruby file: assets/search-atom-xpath-title.rb
  ruby file: assets/search-atom-css-title.rb
  ruby file: assets/search-atom-css-short-title.rb
  ruby file: assets/search-slop.rb

which shows the markdown file being pre-processed for the inline XML and Ruby files.

The point I'm trying to make is that the raw markdown docs aren't very useful without being preprocessed first, and that's why they're currently sitting in the nokogiri.org repository. They're "user-friendly" only in that final form, and so I think being in the website directory is still appropriate for now.

What I was thinking was, though, is instead of trying to peel away pieces of nokogiri.org that might fit well in this repository, can we work within the nokogiri.org repository to first make it a static site? This may be very hard to do. But if we do it, we'll be able to more easily import the entire site into this repository (and potentially just convert the website into an rdoc-generated content).

This is something like what Kent Beck said: "When you have a big change to make, first make the change easy (warning: this may be hard!), then make the easy change."

Hope I'm making sense. I'm not sure there are any easy wins here, but I'd love to get aligned on the path we should follow.

[BurdetteLamar]

I'm not sure I'm following all of your thinking.

However, what I'm thinking would not include importing anything, but instead just writing from scratch new .md files on this site.

This might begin with tutorials, and have other stuff later.