Skip to content

Add more explanation to examples #435

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
chrisn opened this issue Aug 9, 2017 · 3 comments
Closed

Add more explanation to examples #435

chrisn opened this issue Aug 9, 2017 · 3 comments
Assignees

Comments

@chrisn
Copy link
Member

chrisn commented Aug 9, 2017

I'd like to do some work to improve the examples in section 5, with the aim of making the spec a little more approachable to a web developer audience. Specifically:

  • Add an explanatory paragraph that introduces each example, based on the existing code comments
  • Refactor the example code, if needed

Note, I'm not proposing any change to normative spec text. If this sounds OK, I'll submit a pull request in the coming weeks.

@anssiko
Copy link
Member

anssiko commented Aug 9, 2017

@chrisn, contributions to the examples section are very welcome. Examples are often overlooked part of web specs and it's great if you can improve the situation for the Presentation API.

My general suggestion would be to make the examples as concise as possible, while still keep them functional, and omit any bells and whistles.

@markafoltz
Copy link
Contributor

Go for it. I think they cover the basic functionality all right, but probably don't explain the "why" very well.

@markafoltz
Copy link
Contributor

The PR should help in this area, thanks for the feedback @chrisn. If there's further work please open a new issue with specific areas that aren't clear.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants