search

speced / bikeshed

:bike: A preprocessor for anyone writing specifications that converts source files into actual specs.
https://speced.github.io/bikeshed
Creative Commons Zero v1.0 Universal
1.08k stars 199 forks source link

Need a Newcomers' Guide with useful tips and tricks #2080

Open mustaqahmed opened 3 years ago

mustaqahmed commented 3 years ago

I was having troubles with linking to an external definition, and @jyasskin resolved the problem for me using {{}} autolinking. Looks like we need to clarify this in the documentation?

jyasskin commented 3 years ago

I think it's more that we're missing instructions or a tutorial for how a spec author can look at a definition in another spec and figure out what they need to write in their spec. In this case, it was a Javascript function, so I went for IDL autolinking ({{}}) instead of dfn autolinking ([==]), and I knew to look for the for value in the HTML source. We also chose to link directly to a particular overload instead of using the () shorthand.

The current documentation is a good reference, but that's not everything a newcomer needs.

tabatkins commented 3 years ago

I'd love to put together a FAQ section; "how do I figure out how to link to something" is definitely a good one to put in there.

Curse of Knowledge means I don't have a great idea of what else to put in, but any suggestions are welcome.

marcoscaceres commented 3 years ago

In ReSpec, we have a this little cheatsheet: https://respec.org/docs/#Shorthands-Guide

It's useful to see everything at a glance.