search

sketch-hq / SketchAPI

The JavaScript plugin library embedded in Sketch
https://developer.sketch.com/reference/api
MIT License
843 stars 126 forks source link

Improve documentation #421

Closed christianklotz closed 5 years ago

christianklotz commented 5 years ago

The documentation has grown over time and while very detailed in many places it is missing content in others and makes it difficult to find certain information. Another aspect that's been brought up multiple times is a better documentation of changes, see #140, #420 and #411.

This is an umbrella issue for everything related to restructuring and updating the documentation content. Below is a work in progress structure which is split into four sections; the Sketch app, the command line interface, plugin development and the file format.

Each section follows the same structure, introducing wider Concepts and optionally providing Guides for real world use cases which allows for a range of entry level to more advanced content.

Sketch Developer

christianklotz commented 5 years ago

@KevinGutowski I noticed your questions on the forum, your efforts to create some sample code and it sounded like you were planning to put things together in a PR. If this is the case it may be good to coordinate what I'm doing with the stuff you're working on.

As you can see in ☝️ content outline I'm primarily doing two things:

What I'm not doing at this stage is looking at the content of the actual API reference. It feels like the work you've been doing is primarily related to the reference. Is this correct? If true we'd have updates in both areas which would be fantastic 🤗

robintindale commented 5 years ago

Just a note to say I'm happy to review / drop some comments on documentation structure in general as it evolves. Here are some initial thoughts

mathieudutour commented 5 years ago

would be cool to see the early prototype of navigation for these new sections

If @christianklotz wants to open an early PR for feedback, netlify should deploy the website automatically

christianklotz commented 5 years ago

where does the current Examples section fit in? I currently find it kinda jarring that it redirects to a Github repo

That's a good point. My idea is to link to examples in a more contextual way which may make the generic example link in the navigation redundant altogether. This way, a user looking at a particular guide or page describing a concept can then continue after reading and explore the sample code.

the redirect from developer.sketchapp.com => api reference could also be made smoother - but I'm guessing that's part of this

Indeed

there seem to be a lot of plugin guides - I'm not sure if these are individual pages or just a list of things you'd like to include. I think there are probably logical groupings for these guides to make a few pages

Each guide will get its own page, some shorter some longer, similar to Tutorials in the Google Maps API docs https://developers.google.com/maps/documentation/javascript/events.

I'm not sure if the order is representative, but sketchtool and sketch:// url scheme probably shouldn't be given prominence over plugins. They're advanced / slim use cases, the majority of people will want to start with a simple plugin

Absolutely spot on. I've already changed this, leading with Plugins, followed by CLI, file format and Sketch.app.

the old "Your first plugin" was something of a quickstart - might be cool to have an explicit Quick Start page, as some experienced devs may be able to jump off from there, and dive straight into the API reference, without reading much around the concepts

I've already written up a quick start and include it directly on the homepage of the developer website and I hope by giving guides very clear titles it addresses the right audience and makes it obvious for those who are more experienced that they probably don't need to bother with it.

I'm not sure what the Javascript API section will outline that won't be in the API reference. Could easily get out of date if they're maintained independently, so maybe those concepts could live directly in the reference

I'm still playing around with this, my initial thinking to provide something like a Quick start per package but not covering every API call. I imagine code ready to be copy-pasted into the Run script panel and screenshots to illustrate some things better, e.g. within Settings, show a screenshot of the preference panel and explain for instance how this is linked to the analyticsEnabled setting, or something similar.

Should it turn out to overlap too much with the reference then this may not be necessary.

would be cool to see the early prototype of navigation for these new sections - that's key to whether they'll work - how easily visible and accessible things are

I'm going to open a WIP PR later today as suggested by @mathieudutour 😇

mathieudutour commented 5 years ago

I imagine code ready to be copy-pasted into the Run script panel

One thing I considered adding was https://github.com/BohemianCoding/SketchAPI/issues/287. Shouldn't be too hard.

christianklotz commented 5 years ago

There's now a WIP, we're still working on getting it deployed but feel free to run it locally.

mathieudutour commented 5 years ago

deployed here: https://deploy-preview-436--developer-sketch.netlify.com

KevinGutowski commented 5 years ago

I noticed your questions on the forum, your efforts to create some sample code and it sounded like you were planning to put things together in a PR

I don’t have any PRs planned. Those were mostly questions that I had when going through the new Sketch Beta updates so that I could properly talk/share about the new features.

What I'm not doing at this stage is looking at the content of the actual API reference. It feels like the work you've been doing is primarily related to the reference.

Not sure that I follow exactly what you are describing. I felt that the release notes were a bit sparse, particularly from a new dev perspective. Inspired by the “What’s new in Chrome Devtools” videos I thought to put together some posts that explain what the updates are along with any fundamental concepts required to use the new API endpoints. If you think that my “Whats New: Sketch Beta X” posts would be helpful inside the documentation I would be happy to help copy it over to someplace.

Feedback on Improved documentation

Not entirely sure what sort of feedback would be most helpful at this stage so I just wrote some quick thoughts below:

Screen Shot 2019-03-27 at 3 34 28 PM

Here is my 2 second replace HTML content mock

Screen Shot 2019-03-27 at 3 54 15 PM

This is already getting a little long so feel free to reach out via DM/email about the release notes content or if you are looking for more feedback/ideas about how to organize the documentation.

robintindale commented 5 years ago

I'd agree about the top-level navigation feeling a bit off. I think the Sketch docs side-navigation could work well

image

christianklotz commented 5 years ago

I don’t have any PRs planned. Those were mostly questions that I had when going through the new Sketch Beta updates so that I could properly talk/share about the new features.

Ok, thank you for the clarification, makes sense 👍 In which case I may end up using some of your examples at some point to improve the docs 🙂

Inspired by the “What’s new in Chrome Devtools” videos I thought to put together some posts that explain what the updates are along with any fundamental concepts required to use the new API endpoints. If you think that my “Whats New: Sketch Beta X” posts would be helpful inside the documentation I would be happy to help copy it over to someplace.

That would be great! I updated the structure, introducing a Versioning section to plugins and the same would make sense with the file format, where it could be a diff of the file bundle.

image

it would be great if you can borrow some of the styling done for https://www.sketch.com/docs/

Fully agreed. However, for the benefit of improving documentation as quickly as possible I'm focusing on content first before making further changes to the design which I consider a separate task and itself raises further questions about whether Jekyll is the right thing to use going forward.

It would be nice if the JS API Reference was a bit more prominent

Fair point, this could take the place of Blog in the top navigation, also to address @robintindale's point.

I’m not entirely sure if the top navigation should be “Plugins”, “File Format”, “CLI”, and “Sketch.app” … They don’t share the same importance and would have vastly different amounts of content

The difference in content is currently true but our goal is to provide more content in other areas than plugins, too. File format and the CLI are used by many and we certainly can, and should, make it easier for those. While Sketch.app is unlikely to grow hugely in size it is one of the four options how to integrate (into) Sketch.

Another option could be to have a single sidebar with all four parts and the respective sub-sections. However, going back to my earlier point, at this stage questions around navigation are somewhat of a trade-off to avoid a redesign.

KevinGutowski commented 5 years ago

In which case I may end up using some of your examples at some point to improve the docs 🙂

Go for it! Most of the examples that I have there are repurposed from test cases so its mostly @mathieudutour's examples!

Where do you think my examples would be most effective? Under Plugins > Versioning > Sketch {X}?

I like the map that you have. Thats a really neat way to visualize the site.

For the benefit of improving documentation as quickly as possible I'm focusing on content first before making further changes to the design which I consider a separate task and itself raises further questions about whether Jekyll is the right thing to use going forward

Makes sense, wasn't sure what the scope of your changes were going to be.

File format and the CLI are used by many and we certainly can, and should, make it easier for those.

Yeah perhaps if there was a bit more documentation/examples around these I would be more likely to try them out!

At this stage questions around navigation are somewhat of a trade-off to avoid a redesign.

Understood! Its helpful to know the constraints that you are working within.

Is there going to be another pass at the content for older pages? For example, the actions documentation could use a little love. Happy to help document things there.

christianklotz commented 5 years ago

Where do you think my examples would be most effective? Under Plugins > Versioning > Sketch {X}?

This, and I can see some of them being included in the main pages for the different JavaScript API sub-pages in the map. Let's see what it feels like.

Is there going to be another pass at the content for older pages? For example, the actions documentation could use a little love. Happy to help document things there.

I'm moving content from old pages to new one, deleting the old pages and redirect to what I think is the closest someone may be looking for when arriving from an old link. The Actions API is a bit of an odd one because it hardly has any documentation. However, let me phrase it this way – we know actions can do with a bit of ❤️ and we're on it…