Improving Nokogiri documentation

[BurdetteLamar]

I'm thinking to spend time this year with some of the doc here. I see:

• Formats: HTML4, HTML5, XML.
• Activities: parsing, searching, editing, generating.

Any thoughts about what most people are doing? And what could best use the work?

[flavorjones]

Hi @BurdetteLamar! Thank you again for being willing to spend your time helping improve Nokogiri. ❤️

I took a look at some of the issues I wrote up at sparklemotion/nokogiri.org/issues and some of those are still valid and valuable, and other maybe not so much ... I think the ones that might be most valuable -- and what's missing from Nokogiri docs today -- are short how-to documents.

I was recently introduced to https://diataxis.fr/ which describes some mental models for characterizing and improving technical documentation. This 2x2 in particular helped me think about Nokogiri:

Breaking it down:

• Tutorials (learning-oriented experiences) The nokogiri.org site today has a few of these which broadly introduce some concepts.
• Explanation (understanding-oriented discussion) I've started collecting some deeper "why" docs in the /adr subdirectory and in code comments.
• Reference (information-oriented technical description) This is obviously the rdoc strings around classes and methods, which are not superb today but have steadily been improved over the last few years.
• How-to Guides (goal-oriented directions) We basically have none of these outside of a few short examples in rdoc strings.

There is a great book called The Ruby Cookbook which hasn't been revised in nearly a decade, and it has a chapter on XML and HTML but barely mentions Nokogiri (because Nokogiri had not yet been released when the first edition came out in 2006). It's always been an idea in the back of my head to try to rewrite that chapter using Nokogiri instead of REXML.

Anyway, that's what's in my head. Is that helpful at all?

[BurdetteLamar]

A cookbook seems like a good idea. I've done Ruby recipes before, over at CSV. (Those are very old, and may not be my best work.)

Those in the Ruby Cookbook, 2nd Edition may not be the best choices for us (see list below). Suggest we make a list of those we think most important (new Issue?), and maybe gather suggestions from others as well.

In the Cookbook:

12.1 Checking That XML Is Well Formed
12.2 Extracting Data from a Document’s Tree Structure
12.3 Extracting Data While Parsing a Document
12.4 Navigating a Document with XPath
12.5 Converting an XML Document into a Hash
12.6 Validating an XML Document
12.7 Substituting XML Entities
12.8 Creating and Modifying XML Documents
12.9 Compressing Whitespace in an XML Document
12.10 Guessing a Document’s Encoding
12.11 Converting from One Encoding to Another
12.12 Extracting All the URLs from an HTML Document
12.13 Transforming Plain Text to HTML
12.14 Converting HTML Documents from the Web into Text
12.15 Creating a Simple Feed Aggregator

[flavorjones]

👍 I've posted on bluesky and mastodon asking people to comment here if they want/need a recipe for a Nokogiri task.

[BurdetteLamar]

May I also ask on dev.to? (Probably best not on reddit.)

[flavorjones]

Please do! 👍

[BurdetteLamar]

https://dev.to/burdettelamar/nokogiri-cookbook-4p1d