Vela Documentation

[plyr4]

Let's use this space to talk about Vela documentation.

Feel free to talk about what you like, love, hate, anything about the Vela documentation that might help fuel future improvements!

For example share documentation sites that you adore, sections of tech tutorials that are inspiring, or even links to features of sites that you think would help Vela improve the way it represents itself and how to use it.

For transparency, I am prepopulating this discussion with quotes, talking points, and ideas that came from research that was collected in our private Target organization.

Thanks everyone for helping us drive some awesome changes to Vela docs! :)

[plyr4]

i'll start us off and say i wish the vela documentation sidebar would follow me based on what page im currently viewing.
for example, visit here: https://go-vela.github.io/docs/plugins/tutorials/python/

you have to scroll the sidebar to see which item is the currently-visited page.

[plyr4]

From another users:

Most of these suggestions are cosmetic.

For the external site, I'd like to see these get implemented:

Sections in the left sidebar are collapsible/expandable.
Better highlighting of the current page you're on in the left sidebar.
Table of contents on the right sidebar for ALL pages for easy navigation. Some pages have it, others don't.
Better search. Show search term in search results instead of just the page name.
Improve callouts. Here are some examples. It'd be neat if they were rich (e.g. collapsible, able to embed code snippets).

For the internal site, I'd like to see these get implemented:

Better search. Show search term in search results instead of just the page name.
Color scheme, font family, and font size that are easier to look at.

[plyr4]

Q: what are peoples favorite tech doc sites? and why? what do they do well? what would you improve if you could?

[plyr4]

https://docs.dyte.io/ built with docusaurus is nice. love the search bar and slick top menu dropdowns

[plyr4]

https://elm.land/guide/ is another example, built using Vitepress. again, the search bar and the page composition. i appreciate the book-like pagination of content that reads easy for the user.

[wass3r]

Came across this: https://awesome-docs.gallery/ . Not certain what their criteria is for quality doc site but it lists a few I do like for various reasons.

[plyr4]

@dtanner said:

questions to help focus:
what are the support requests coming in?
how many people are using managed auth for a new project vs migrating from an existing project? guessing it's by far the latter
if it's a lot of migrating an existing project, i think a dedicated page on migrating an existing project would help a lot

rephrasing the question - along with continuing to polish our our existing docs, what documentation perspective(s) are we possibly missing? those styles being

• learning-oriented tutorials
• goal-oriented
• understanding-oriented
• information-oriented

my first impression is that one thing we're missing is a comprehensive goal-oriented doc page on migrating apps from plugin version to plugin version

[plyr4]

@wsan3 said:
https://docs.divio.com/documentation-system/ outlines a lot of good principles and practices that should be referenced.

[plyr4]

something users often ask for is "more tutorials" and "more examples".

Q: what does that look like, and how does that differ from what we already offer?

[plyr4]

@wsan3 said:

I think our quickstart examples could be more detailed.

For example, looking at the Go example, it might be helpful to include project setup steps, line-by-line explanation of the pipeline config file, screenshots of a successful build, and so on. A line-by-line explanation of the pipeline config file would give us the opportunity to direct users to fundamental pipeline concepts. We could also surface templates to the users in these quickstart examples.

Some references:

Hugo quickstart
Actions workflows

[plyr4]

reposting a really good idea from @chrispdriscoll that was posted to our backlog

specifically calling out this bit:

The intent of a Common Troubleshooting page should help guide the user through logging levels and various considerations they should investigate before posting for help in forums, slack channels, issues etc

any explicit examples that we should consider?

[plyr4]

so, building out this more? https://go-vela.github.io/docs/faq/usage/ (which is linked at top of support channel as well)

[plyr4]

@wass3rw3rk said:

for now, just a dump of some existing documentation sites for CICD tools for reference since i had the tabs open. no commentary right now as i wanted to take a more in-depth tour of each myself:

https://woodpecker-ci.org/docs/intro
https://kraken.ci/docs/
https://flowci.github.io/#/
https://docs.cloudbees.com/docs/cloudbees-codeship/latest/
https://codefresh.io/docs/
https://docs.codeclimate.com/
https://cirrus-ci.org/guide/quick-start/
https://docs.gitlab.com/ee/ci/
https://confluence.atlassian.com/bamboo/bamboo-documentation-289276551.html
https://concourse-ci.org/docs.html
https://docs.semaphoreci.com/
https://buildkite.com/docs
https://circleci.com/docs/
https://docs.travis-ci.com/
https://docs.github.com/en/actions