Teletype docs enhancements (redesign in progress)


#261

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.

The idea I had around that was expanding all menu options for mobile. So if you wanted to get to a specific op, it should be always visible in the list to be able to be clicked. you don’t have to open the Ops parent link first to see it.


#262

Also, I had some stuff come up and will not be able to get things finished up for a PR this evening. Will get to the rest of things soon.


#263

Understanding that all this is mostly an update to make it more comfortable on a mobile phone I checked it with my iPhone now. And I might have to say in advance that I am a bit traditional and find it much easier to navigate on iOS by using gestures for zooming in and out on oldschool web pages than using phone ‘optimized’ design wich is mostly bold and simplified/minimalistic, and therefore harder to include a lot of information.

What I liked about the tables is that you get a better overview and it feels easier to me to find something without endless scrolling. Especially the alphabetical section I find hard to use on a phone. When you look at iTunes for example there is a sidebar with the alphabet to help navigate, where, again, it is not always easy to hit the right initial (at least when you use a phone that is not a tablet…). Maybe we could at least condense the list a little bit?

If the always expanded design for the menu is easier to program I can see what you are going for. On the other hand the open menus for Updates, Quickstarts and Changelog seem a bit distracting for my every day use. I would prefer it generally always closed so you could just open the chapter you are looking for and then jump to the op you are after - like on the computer.

On an iPhone 5 the top part of the screen which contains only the menu button takes a quite big part of the whole interface. It allows less of the information to be displayed and doe snot seem necessary:


#264

Good feedback to reduce the size of the area around the menu opening. I agree that it takes up a lot of space.

Also, to clarify, the alphabetical list of ops will be moved back into a table before release. I just haven’t done that yet.


#265

Not sure if anything like this has been discussed but:

One thing I always loved about Max/MSP was the insanely rich learning scenarios that have been embedded with the software. The help windows, and the ability to cut and paste selected items from them, made for some of the best self-learning environments in my experience.
In any case, I was reminded of this, as I am scrolling through this thread.

And so:

am wondering if implementing something like the “see also” menus or selections, that would link to related elements of Teletype scripting language. If these were links to those portions of the docs, it would also help navigating through the files (less scrolling). I understand that this would be a huge task to undertake, but thought I would bring this up for the sake of conversation… thoughts?

maxresdefault patch2


#266

This reminds me of the Teletype studies! Although I guess a small working snippet to explore is a little bit different, and more amenable to being part of a manual rather than a learning-guide.


#267

Yes, the “Reference” section of Teletype studies does sort-of function like that. Though it mostly simply recaps the commands etc. used in the study.

The “see also” branches out into other, but related objects etc. effectively helping to expand the frame of reference and better understanding of the ecosystem.


#268

One thing I always loved about Max/MSP was the insanely rich learning scenarios that have been embedded with the software.

sandboxed, emulated environments are awesome, kind of like the max/msp examples you mention, @laborcamp. recently, in the react.js community, a tool called CodeSandbox has gained a lot of traction.

am wondering if implementing something like the “see also” menus or selections, that would link to related elements of Teletype scripting language. If these were links to those portions of the docs, it would also help navigating through the files (less scrolling). I understand that this would be a huge task to undertake, but thought I would bring this up for the sake of conversation… thoughts?

Linking may be something we could leverage without changing any thing on the pandoc or the templates. each section of the doc has an id, and we may just be able to do something like [#specific_section](see more) within the markdown for a particular doc page. In other words, I think this would be more of a content, rather than a code change.


Also, just so its clear, excited about the future of what we can do with this (and other monome projects) web docs, but my priority #1 is to get my current pass PR’d, merged in and push to the monome site. So I am pretty set on the bug fixes and the enhancements I’ve outlined above, and I don’t want to add more changes in this “release”, so that we can get this up and useful for people (and also so I don’t burn out on doing this stuff, heh)


#269

Apologies for the slow reply to this! I’m also, in the end, pretty ambivalent re. the dashes; I figured they’d be helpful to keep the layout of each OP block clear, but I have no problem getting rid of them if they’re impediments!


#270

Also, hats off to you @jlmitch5 – you’re doing an amazing job consolidating all of this feedback and building what will no doubt be a great, flexible solution.


#271

I think I fixed the sticky header. That was much more difficult than I anticipated. I don’t love that the x scrolls when the menu is open–might come back to that another night this weekend (but for now I’m tired of messing around with that).

Still need to:

  • gridify alpha ops again, with one column for code, and one column for short description
  • add separator between content and start of table (awaiting design @Olivier – thanks @alanza )
  • update tab title and add favicon

Hopefully will get that done this week.


#272

updated link with re-gridified alpha ops and a separator between the categorized ops tables and the next section. I think I’m finished with all the enhancements I want to get done in this pass. I’ll do some slight code clean up tomorrow and submit a pr barring any issues.


#273

this layout for the alphabetical list is so clear!! I love it.


#274

thanks, visually heavily inspired by the table in @Olivier’s original mockup.

I think it could slightly be improved with a docs rewrite of the grid ops. the variables are not always single letters, so they wrap. also the short description doesn’t include info about what those variables do.

G.GBX group id x y w h type level script columns rows | initialize multiple buttons in group

could be something like

G.GBX g x y w h t l s c r | initialize multiple buttons in group, where g is the group id, x and y are coordinates based on the top-left of the grid, etc.


#275

This is looking great. Though it looks like there are a lot more OPS somehow :slight_smile:


#276

Thank you!

Not sure I follow. Is there an issue you are seeing?


#277

No issues at all…I just meant that looking at the cleanly laid out long list it feels like a mile long. It’s beautiful work that’s been done here.


#278

Ah gotcha, yes it’s awesome how many ops there are!

Also glad y’all pushed for putting this back in a table. I think it works really well for a quick reference laid out like this–I can see myself referring back to this now.


#279

Hm, seems to be somehow broken - when I try it on the iPad I get this:

Unfortunately, tapping on the links does nothing.


#280

Hmm this looks to be like the JavaScript isn’t running to transform those links, I’ve ran into this before. It works on iOS (iPhone) for me—just tested it. Can you double check a refresh doesn’t fix this @Leverkusen