IE-0028: Extension documentation

[curiousdannii]

(IE-0028) Extension documentation revisited

Proposal: IE-0028
Authors: Graham Nelson
Language feature name: --
Status: Draft
Related proposals: IE-0001, IE-0017
Implementation: In progress

Summary

To make extension documentation richer and more visually comprehensible.

[zedlopez]

doc_line_counts.txt
I would suggest one page per example and one page for everything else. Extensions often have a lot of short chapters... naturally, no one chose the break points thinking they'd be split up. Being unable to look at the whole of the docs on a single page would often make things harder to apprehend. (Or at least it would for me, and I suspect I'm not unique.)

[edited to add the evidence. The numbers are the number of lines until the thing below it, or, for the last entry per extension, the end of file]

[ganelson]

So, the reason I disagree about this (i.e. splitting so that each chapter is a page) is that some extensions do need more, or at least could benefit from more.

I agree that most extensions don't need that, but this is what Sections are for. It's completely legal for an extension's documentation to be divided into, say, an introductory chunk of text and then four Section headings, with no chapter headings at all. If so, then the result is exactly what you're suggesting - all the documentation on a single HTML page, with each example then on its own page.

And in fact it's legal to have no headings at all - Locksmith has none, for example.

[zedlopez]

A modest proposal then... admit Parts to the extension documentation header family and put each part on a different page. This way, all the existing extensions' docs appear on one page until such time as they're revised to use Parts; any new extensions have the option of using Parts, and we get to have 2 levels of headers (Chapters and Sections) on a page, and surely there will be contexts where that's useful for organization.

I submit that it would be less work to edit those extensions that would truly benefit from multiple pages to use parts than it would be to edit all those that would become choppy and disjointed from chapters becoming different pages to cease using so many chapters.

[ganelson]

That seems such a completely reasonable proposal that I'm struggling to work out exactly why I'm against it, but I still am, I'm afraid.

I don't think I agree about the disjointedness, because it seems to me that the experience of reading these documents in a pane of what is probably a laptop screen is such that it's not unhelpful to have them divided up. It's what the regular in-app manuals do, too: those are divided into chapters and sections, but not parts.

[zedlopez]

I'll make one final plea, then drop it.

It's also my opinion that the inability to view more than one section of a chapter in the docs at a time impairs comprehensibility and usability; this was a substantial part of the inspiration for going to some bother to reformat them. It's easier to find things when you have the option of using a browser's find-in-page search on a whole long page, and I find it much easier to find things by scrolling around and being better able to take advantage of a feel for things' position relative to each other than by needing to find the exact number of discrete steps to get to the exact correct page.

That said, you wrote the docs and (I presume) understood the intent to display them one section at a time long before they were finalized. But dozens of people wrote the extensions' documentation, without any expectation of the presentation becoming other than monolithic at some future point. I don't know whether you looked within my doc_line_counts attachment above, but you'll see that there would be lots of chapters with line counts in the single digits, sometimes more than one in a row (even if we ignore the ones where that's clearly not a problem, like a short final "Change Log" chapter). The division of the docs into Chapters and Sections thus isn't analogous to the division of the extensions' docs into Chapters and Sections, despite the names.

Scrolling through large chunks vs. paging through small chunks seems very likely to be a cognitive/learning-style difference where neither of us will really be able to feel why the other one has the preference they do. So I'll just conclude by noting that the proposal to add Parts would add flexibility and support a larger variety of chunking-styles, and I believe defaulting to all-chapters-on-one-page for the existing extension documentation as written will better correspond to the existing authorial intent.

[curiousdannii]

Maybe single page extensions could continue to have single page documentation, while chapter=new page would only apply to extension folders? Then people using chapters as they should use sections wouldn't be an issue.

[ganelson]

I keep thinking Zed is probably right, and yet, and yet. I'd certainly be happy to go with Dannii's compromise suggestion. Zed, would that be a reasonable outcome, from your point of view?

[curiousdannii]

Just had the thought: If the public library is going to convert all extensions to directory form, then the criteria should actually be embedded documentation vs Documentation.txt.

[ganelson]

Also reasonable. Though I hope people will want to convert - testing is so much nicer if you do, I've found in my experiments.

[zedlopez]

If we can't have pages = parts, Dannii's suggestion seems like a good one. But I'd already been planning to deconstruct the 10.2 extensions, and if I do so, it kind of ends up being a no-op.