Where should we put our docs?

[necaris]

It seems as if we have several types of content that fit under the general banner of "documentation", and that we're currently thinking about where to put it.

• API documentation, i.e. what's currently on docs.coiled.io
• tutorials and examples
• issues that people have faced (i.e. this repo, and our community Slack)

Dask's current solution for this, with various subdomains of dask.org for various things, has caused confusion in the past.

Current suggestions for where these could go in the future include:

• API documentation staying where it is
• tutorials and examples going on our blog (although that may cause confusion with marketing efforts, and be hard to find)
• tutorials and examples going in some kind of knowledge base solution, e.g. Hubspot
• issues that people have faced going to a more commonly used ticketing system, e.g. Hubspot

[pavithraes]

I'd be in favor of having all documentation in one place. Especially because a user might expect to find all (API docs, tutorials, examples, and some FAQs) of these in "documentation", refer to these together, and maybe search for something through all of these at the same time?

I like the top navbar implementation in pandas. Could have each main documentation genre there, and we still have the opportunity to have topics and subtopics within each genre's left-navbar. This does assume that tutorials and examples won't get too extensive though, which might get tough to maintain.

issues that people have faced going to a more commonly used ticketing system, e.g. Hubspot

I think this means all the previous issues, and I like this idea. :)

[sandhujasmine]

+1 keeping all docs in one place. I imagine the blogposts may keep increasing so at some point, some of these may need to go elsewhere but I'd say keep them in one place for now.

Not sure about tickets/knowledge base.

[ndanielsen]

I suggest opening up additional channels for soliciting feedback about documentation if a user is unable or uncomfortable for various reasons to do it here.

I think an additional channel could be the Coiled Community slack group.

If email was a valid channel for feedback about this, where could they send it to?

[necaris]

@ndanielsen that's a good point! Folks should feel free to DM me / us, or email support@coiled.io too!

[jrbourbeau]

I like the top navbar implementation in pandas. Could have each main documentation genre there, and we still have the opportunity to have topics and subtopics within each genre's left-navbar.

+1 I'm in favor of this idea

[gryBox]

I think one of the considerations concerning tutorials and examples is -- Where can developers easily keep the material fresh? And easily found via the web and (API) documentation site.

[GenevieveBuckley]

+1 for the top navbar idea

napari tries to do something like this. There's the main page, then the API docs, and the tutorials. The tutorials are hosted in a completely separate repository, so the navbar is an attempt to make all these things easily accessible from one place. I should mention there's a push to improve the website right now, so things are a bit in flux there.

[FabioRosado]

Thank you all for the great feedback, we have put the knowledge base together with our documentation page. I am closing this issue now, but if you have any other feedback or suggestions, please feel free to open a new issue.