Teletype docs enhancements (redesign in progress)


#241

If anyone is tempted to try that, you might want to wait a bit, the image is 2.43GB! Let me see if I can clean up the cross-compiler build folder after it’s built.


#242

I think one of the main concerns with LaTeX is that the standard distros are multi-gigabyte downloads, which probably seems increasingly burdensome the less likely you are to use them outside generating documentation and the slower your internet is.


#243

That’s a good point. Ideally we can get to a place where nobody has to do any manual installation or building and it can all happen automatically in :cloud: :rainbow: the cloud :rainbow: :cloud:.


#244

very nice! since you’ve already dockerized it (and the repo is public), it’d probably be pretty easy to configure CI to pulldown that container on the branch. ZEIT now could do it I think (and I’m sure others). Unsure about the output-the-build-artifacts part of things


#245

weird that the posts that got moved to this thread are not arranged chronologically, never noticed that before…


#246

Some text in the Ops/Mods section appears to be rendering incorrectly on my phone (Samsung S9+ running Chrome) . The right-hand side is running under the padding(?). I have attached a screenshot.

Although I predominantly use a printed copy of the pdf manual, I do refer to the web version on my phone from time to time. I love this new, clean design and will certainly use it more often.


#247

I don’t believe @tehn has been able to download Latex precisely because of this.

On the flip side, at least one of the contributors to the first version of the docs did it by only building the HTML output.


#248

I have worked to get my TODO list up to date based on all the fantastic feedback everyone has provided. If you don’t see something on there that should be or you find any other bugs, please let me know!

Working on defining these a bit more.

  • ENHANCEMENT: improve display of alpha ops somehow (put back in grid? move get/set to be vertically stacked in said grid? link back up to categorized ops/mods section?) (thanks @alanza, @sam @Leverkusen and @scanner_darkly)

It seems like the concensus after reading back is that it probably needs to be in a more compact table form. To help keep this terse and parseable, I like the idea of keeping things in two columns–syntax stuff in one and short description (if given) in the other. This will give more breathing room for the description and not require tons of wrapping, hyphenated words, etc. I think that “special” syntax for setting (or whatever) should ideally be called out in the short description or fairly clear from convention. We can update the documentation around any issues there. Let me know if this plan doesn’t make sense, happy to alter.

  • ENHANCEMENT: improve ux of toggling/untoggling primary nav links (thanks @rryy)

I explored keeping elements open when others are clicked in the course of development and it starts to make the experience of using the nav feel a little “buggy”. I was thinking along your line of thought you mention in your scenario–that it’s slightly “more clicks” to get back to a place or between sections. I’ve been thinking through potentially adding some sort of + icon that is to the right of the menu items so they could be opened without being clicked, though I think that might just end up being ambiguous to someone coming into the docs and just feel a bit like clutter.

Note that one benefit of keeping things more “compact” is that there is less sub-section stuff to wade through and parse “where you are”. It’s a bit nice having fewer elements available for you to parse to figure out what’s available in the docs, if that makes sense.

Still thinking on this one.


#249

Thanks for your efforts here! I have not read this entire thread so apologies if this is a duplication.

Whatever is used to render this out to a web page seems to have some quirks with viewing it on an iPad. It looks good, but navigation is weird. The normal “flick to scroll a lot quickly “ gesture seems to be disabled. And if you use the menu to navigate somewhere, then close the navigation menu (which seems to require two touches on the X), then it moves to a different place than where you navigated to.

This is on iOS 12 and Chrome browser. Not the end of the world but I thought I’d post the experience.


#250

To me the suggestions sound good, while I am not sure if I really understood, how you imagine the op-table. I had a look over the layout proposed above and it seems to me that one column for syntax and one for the short description should be fine in most cases, with get/set in the text to show that ‘set’ is possible and follows the convention.
Also two rows per op would allow one row for op syntax and one row for the alias, if there is one, and should be enough for a short description to look up.

Regarding the menu, I think it is okay to have only one element open as it is not that deep and you can reach everywhere easily. Plus it looks cleaner when all but the current element are unfolded.

Thanks for your work on this - I am sure it will end up as a beautiful and versatile tool!

:grinning::+1:


#251

@EqualTemperament thanks for bringing that back up–I missed @scanner_darkly mentioning it when I was going through and updating my list of left things. Added!


#252

I pushed some updates, url here. Will try to finish up the remaining enhancements tomorrow.

  • FIXED: fix scrolling stopping on iOS (thanks @scanner_darkly and @EqualTemperament)
  • FIXED: fix unordered list rendering (see below for screenshot – thanks @tehn )
  • FIXED: fix wrapping of ops “tables” (lists). check with android chrome – thanks @rikrak
  • FIXED: fix back button not updating state/location, potentially using hashchange fn – thanks @rryy
  • IMPLEMENTED: tweak css and styling to reduce prominence of sidebar based on feedback (thanks @Leverkusen and @olivier)
  • IMPLEMENTED: be consistent with name used for external devices (full manufacturer company/product vs. shorthand)

#253

This is working, and so much nicer. Thank you!

Navigating from the menu still has a strange behavior on iPad. If you navigate from the menu, you are taken to the correct anchor. But if you close the menu, it moves. It seems to take you several pages down.


#254

Glad it’s working better!

Because the structure there will be different because the menu opening icon will stick to the top of the screen, I hadn’t really looked at that yet—I’ll make sure to check this is fixed when I make that change.

Thanks!


#255

Looking good on Android Chrome now.


#256

I like the smaller side bar, just could not find a way to fold up the menus again without unfolding another one.

I am not so sure about the long and widely spaced list of operators though. It feels like endless scrolling and I liked the old tables more, I think. It just felt easier to grasp an overview and find something. Also there was a clearer distinction between table/list of operators and introduction per chapter, which also made the distinction between chapters clearer.

Within the alphabetical list I would not need elaborated explanations and code examples. I think just the syntax and a few words what it does would be enough there.


#257

looks great! (and with ios scrolling fixed feels much better - thank you!)

i like the cleaner look for ops but can see that a table format might work better. my earlier point was eliminating separate columns for setters and aliases as not every op has them, so it just creates 2 columns that take space without providing much value (and having borders around each cell separated ops and their descriptions too much).

perhaps a table view for alphabetical list and keep the current format for the main list? also if there is a way to link from the alphabetical list to the main list so you could easily jump to a more detailed description could be a good option, but not sure how much work that would be.

for the ops that don’t have a setter or an alias it shows a dash instead - should we remove those? not sure they provide much value but they do take space.

thank you, great work, and big thanks to everybody else helping with this!


#258

Thanks for the feedback @Leverkusen and @scanner_darkly, very helpful.

The top level menu items currently act to open the list of sub items, Since they are links themselves and not just headers, they don’t make as much sense as toggles. The ux there is a bit weird and I’ve got a follow up todo to look at that sometime in the future after release (and of course, would be happy to help guide on that if anyone else is interested in developing that)

I plan on re-gridifying the alpha ops list today (along with a few other enhancements—I have my remaining todos marked in an edited post above). Agreed linking to the expanded list section would be awesome—need to figure out how to be able to pass html IDs to the jinja2 markdown template to make that work.

The dashes when no value can be easily removed from the categorized ops section. The point was to keep the sub rows consistent for each row of data. I’m ambivalent cc @Olivier, thoughts?


#259

EDIT: actually realizing some issue here, will come back to this later this evening.

@EqualTemperament can you test anchoring again at the link. I implemented the fixed menu header and fixed anchoring with this trick and it seems cool on my iPhone. there does seem to be some strange scroll bar appearances that hopefully I can figure out how to make go away.


#260

Working much better! Only downside is that the menu disappears immediately when you click on something. I.e. if you click to expand the list of ops, you get taken to the top of the ops section. But the menu disappears before you can choose a specific op and must be re-opened to do that.

Still, in my opinion, this is preferable to it completely losing your place like it was doing before!