20

As per the documentation update of november 29th, a "Introduction" section was added for documentation topics.

Since I "abused" a pinned example to serve as an introduction, on a topic I wrote, I figured I'd remove the example, in favor of using the new introduction section.

When trying to save the draft, I got hit with the following error:

"Introduction must not be longer than 500 characters"

As is, the introduction (/pinned example) is currently 1597 characters long.
The text / table makes up only 845 of those. The remaining ~750 characters are just url markdown.
The rendered text is 752 characters long.

I'd like to request for the character limit for documentation introductions to be increased. Preferably something like 4-5 times the current limit.

12
  • 17
    Fun fact: Comments have a 600 character limit. You can write a longer "intoduction" in comments than in the "introduction" section.
    – Cerbrus
    Commented Dec 2, 2016 at 7:52
  • Funner fact: no one reads this stuff anyway.
    – Cody Gray Mod
    Commented Dec 2, 2016 at 19:45
  • Could do that twitter thing where you just put all the text in an image. This would also spare folks with screen readers.
    – Shog9
    Commented Dec 2, 2016 at 20:17
  • @Shog9 couldn't add the links, then....
    – Cerbrus
    Commented Dec 2, 2016 at 20:19
  • 1
    Arguably, that's the job of the topic outline at right anyway. BTW, it won't help much here, but... there is a shorter URL syntax for examples (/documentation/s/e/6837 from within Docs).
    – Shog9
    Commented Dec 2, 2016 at 20:28
  • @Shog9: I'd agree, if the topic outline were cleaner / had a better overview (Like the sidebar that was removed for some reason)
    – Cerbrus
    Commented Dec 2, 2016 at 21:16
  • Maybe you could edit to explain where the topic outline falls short? I don't remember the previous sidebar.
    – Frank
    Commented Dec 5, 2016 at 20:27
  • @Frank: Readability, overview, formatting, sorting. The topic outline doesn't come anywhere close to the table I provided in the pinned example regarding usability. What also doesn't help is that the first few examples (Sorted by votes!) are expanded by default.
    – Cerbrus
    Commented Dec 5, 2016 at 21:33
  • With detailed info to convey, like your table, I'd drop it in the Remarks section and refer the reader there. (That's what I did today: stackoverflow.com/documentation/review/changes/114162 ) I plan to use the intro section just to say "Here's what we're talking about and a strong recommendation to check out the official docs (if any)." As a side note, manual sorting kind of runs counter to the whole democratic "on SO, votes determine quality and hence ordering!" idea, eh.
    – Frank
    Commented Dec 5, 2016 at 21:56
  • Although, actually, I wouldn't drop a TOC like that anywhere, since it demands maintenance from all future editors (in case js, I don't know, renames, drops or adds an operator). I sort of fall in the "use topics as tasks" (instead of lists of things) camp: meta.stackoverflow.com/questions/329183/…
    – Frank
    Commented Dec 5, 2016 at 21:58
  • 2
    @Frank: Moving it to the "Remarks" means you'd have to navigate to the bottom of the page first, to find what you're looking for. That's bad UX. When I think "Documentation", I expect a clearly laid-out page where I can see in one glance what topics are covered there. A table like that is perfect, in that regard. I don't see the "tasks" idea you linked turning into anything maintainable...
    – Cerbrus
    Commented Dec 5, 2016 at 22:08
  • My idea is not to count links to the character limit, because they're not displayed (readers don't have to scroll because of them) and they are usually long without an easy solution to shorten them (unless you want to use goo.gl everywhere, which is not a good idea I think). Even just link to this question has about 100 characters. That is 1/5 of the allowed length Commented Jan 1, 2017 at 11:56

1 Answer 1

6

Observations

The example you cited is composed of two parts. The first is very much the sort of thing we expect in a Topic introduction:

Unary operators are operators with only one operand. Unary operators are more efficient than standard JavaScript function calls. Additionally, unary operators can not be overridden and therefore their functionality is guaranteed.

That weighs in at 230 characters, which is well within the limit.

The second part is a very nice table of contents of the other examples in the topic. As you know, there's an automated outline in the sidebar:

Table of cont

Clearly, the manual index is a better way to guide people through the Topic. (Though I do think it would be slightly better if the third column were removed and the link added to the words in either the first or second column.) Instead of the essencially random order of voting, you can order the examples logically. You also are able to give a quick summary that might save readers a trip to the example itself. Finally, there's no need to colapse the table to save sidebar space.

Analysis

You've asked for a longer introduction section, but it seems to me that the underlying problem is actually that you want to be able to add structure to the Topic. Expanding the length of the Introduction section would help you solve that deeper problem. But it's not the only potential solution. In particular, a better and perhaps manually honed table of contents would also satisfy the need. (Assuming I'm reading between the lines correctly.)

As a rule of thumb, automated indexing works best with dynamic material, but manual indexing is more accurate for static content. Documentation Topics tend to be more dynamic, but for topics like Unary Operators in JavaScript, it's unlikely more examples will be added anytime soon. So in an ideal world, it would be possible to override the automated index when a Topic is more or less fixed. Or maybe allow more control over the order of examples and improve their titles.

Thinking about Unary Operators, it might be helpful to link to other types of operators somewhere. This gets to a concern raised early on: Documentation doesn't have enough structure. This is on our backlog for future work, but we think the discussion tab is more urgent.

Conclusion

We are certainly open to changing the character limits. But we probably don't want to support handcrafted table of contents in the introduction section. It would be far better if we could improve the automated table of contents feature for all topics.

2
  • An override on the index would be the solution, yes. But then, it should be allowed to be a little larger than what's currently available at the side of the screen...
    – Cerbrus
    Commented Dec 8, 2016 at 10:54
  • 1
    500 chars is just too small. I hit it easily with around two sentences and several links. Clearly, you don't want people writing books, or even chapters, but any limit that is set will end up being inappropriate for some subject. It seems like a better approach would be to let the community police/condense/correct sections that end up too long. Heck, even this comment can be longer than 500 chars. I don't think that terseness always improves documentation.
    – Dweeberly
    Commented Dec 15, 2016 at 1:53

Not the answer you're looking for? Browse other questions tagged .