#1

this is perhaps a minor technical detail but it has substantial ramifications: i’ve (finally) moved the hosting of the monome documentation to github pages.

the docs were already a github repository, so integration with pages means that they can now be updated/published instantly without some fiddly scripts i have to personally run… so management can be more collaborative.

secondarily and equally great— the css/layout is now all exposed within the repository, and so we can more easily discuss/improve the meta-issues of the docs such as presentation and formatting.

i’ve already started a list of web styling improvements— feel free to add. (and also, calling opinionated visual web designers for critique and help on implementation… most of these edits are small but fiddly).

@dan_derks and i will be restructuring the docs and fully combing them in the coming weeks. so this is a good time to hear suggestions.

thank you to everyone who has contributed information!

55 Likes
Norns shield
#2

Thank you all for this awesome effort.

4 Likes
#3

Is there a “Style Guide” for markup conventions, etc?

(If not, then perhaps a wiki page for that?)

1 Like
#4

Amazing. I’m happy to help out with visual feedback (and maybe a css tweak here and there)!

#5

This is a wonderful development, thanks! Now we can all help out, coder or not.

#6

re: further docs additions/critique:

further documentation of the more common max apps would probably go a long way if there’s anyone up to the task

but short of that I also don’t dig the way that they’re split between the grid page and and “applications” nested under that.

maybe a “desktop” section makes the most sense alongside norns/crow/modular. kinda wonky with programmable things alongside grid/arc that now operate with multiple programmable things. I can see about a PR for that if it makes any sense.

2 Likes
#7

There isn’t really; most are written in Nice Sensible Markdown, ie, headers in descending order, use plain HTML, it mainly works.

Most of the docs I’ve done edits or work on never went much below h3.

Beyond that, regarding prose style… I’ve just tried to emulate what was already there. The main one that tripped me is that the things you push on a grid are largely called keys, so I stuck with that when working on the Ansible docs.

1 Like
#8

This is a great development!

#9

Very awesome stuff!! I opened up an issue to move the teletype webdocs to using the css from this new repo https://github.com/monome/teletype/issues/187

#10

the TT webdocs (manual, that’s what you mean?) i think look really good actually.

this is to say, i’m not super attached to the current look of the monome docs. there is some nice consistency with the front page of the monome site (which i really like) but that is a very different thing than document presentation.

so i’d be up for a whole new design proposal for the docs (ie, searchable, sidebar, etc) if someone is passionate about it!

(to reiterate, just looked at the TT manual again and i think it’s great!)

1 Like
#11

That works to! I feel like I saw someone talking about enhancements to the styling of various markdown things (was it you @dan_derks?) I can’t find it right now. When I saw that, I was thinking…ah, when that settles I could update those kids of things on the tt docs so the look and feel is consistent.

#12

i think you mean this linked in the OP?

it’s pretty minor stuff if you want to take a stab at it— mostly an aesthetic judgement actually.

what i was suggesting with a format/layout overhaul is more ambitious :slight_smile:

#13

First of all, thanks for doing this!

I hope to be able to help contribute to fixing the Teletype documentation rather than just complaining about it :stuck_out_tongue:

I’d like to see the following things happen if possible and if others think it’s a good idea:

  1. Remove ‘Updates’ and combine that content with the ‘Changelog’
  2. Move ‘Teletype studies’ into the manual after ‘Quickstart’ with a subsection link for each part

I’m not sure what the process would be for this. Do I create a separate issue for each of those things and the discussion for each happens in the issue? Does the discussion continue to happen here? If people are up for those changes, do I just make the changes and open pull requests on github?

#14

This is a cool initiative! I’ve been thinking about how to leverage the really helpful and insightful content that gets generated on lines. One way to handle this would be to allow users to flag lines posts that they find really helpful for future inclusion in docs.

This could work much like the flag post feature, except that you would flag the post for being very helpful, not offensive. Flag for crow-docs, teletype-docs, etc. These flagged posts could be picked off in later docs pull requests.

edit: discourse supports tags, so maybe something like #suggested-doc for this

2 Likes
#15

Since that (excellent) suggestion would require modifying the discourse software and as a result might be a large challenge to implement and maintain, perhaps an alternative would be to have an account named something like @crowlibrarian and whenever someone finds a post that is especially useful for crow that person shares the post to @crowlibrarian. The person managing @crowlibrarian can then assemble and post the links wherever they’re supposed to go.

3 Likes
#16

i think you can specify hashtags in discourse forums. for example, ##norns >> #norns

1 Like
#17

Who would do the translation from a post to the docs?

#18

Contributors interested in submitting pull requests to the docs repo I guess?

1 Like
#19

I added two issues to the github repo, i think a basic search and nav would be beneficial. I’d like to help somehow :slight_smile:

#20

I, of course, would never expect this so soon, but something perhaps to stew on for later: Crow seems to be just as complex as Teletype, and I’d argue that its relationship to other devices/systems makes it even more so. When I racked mine last weekend, I found myself with a lot of tabs open on my laptop trying to piece the story together.

I could see a future where crow gets the interactive manual treatment – a central place to collect the following: description/overview, version changes, update procedure, context info (m4l, norns, druid), syntax conventions, ii commands, etc. Basically a module-specific version of what @eblomquist is suggesting in Looking for collaborators on proposal for Index/Learning Center

EDIT: Totally forgot that @dan_derks suggested exactly this here!! 100% support!!!

3 Likes