Juju Docs - Charms Development/Juju user separation


#1

Hello,

As a newcomer to Juju I love the technology and it has massive potential, but I keep bumping into an issue with the docs.

This issue is that the docs seem to be blurred between juju user guides, and charm development - it feels as if some pages include the information required to be able to do something in juju, whilst others talk about how one can develop charms.

It would seem logical that these two topics would be better separated, maybe something like dev.jujucharms.com and docs.jujucharms.com to give a ‘goto’ place for developers, and people who just wish to deploy respectively.


#2

The charm writing pages are rooted in the Charm writing guide (linked from the left menu). Naturally the User guide and the Charm writing guide will refer to one another in certain places.


#3

I understand this, but do you not feel that in parts they should be separated? I’m not asking for help - merely a discussion/point of view.


#4

I get where you’re going with this.
I somewhat agree, but at the end of the day whether you’re a mere mortal or a dev hero, you still need to read the “documentation”.


#5

There will be more work in this divide/area in the future. I appreciate the feedback but I’m personally not sure “more site urls” is the best approach. More clear navigation/separation though is solid feedback we can look into as we work on next step plans.


#6

Thanks for raising this. This kind of feedback is really important - most people don’t complain, they just get confused and give up.

I actually think that we could partition the documentation into something more granular. It would focus on workflow/use cases. Here are some ideas. How do they sound?


Juju use cases

end users who want to make use of the public charms

  • beginner: getting set up with credentials, clouds and being introduced to the terminology
  • becoming familiar with juju deploy
  • understanding the distinction between the charms and the “promulgated” charms
  • using relations

using juju to manage in production

  • adding units
  • cleanly tearing down
  • power user: new workflow, customise charms with config.yaml files, write basic charm that wraps legacy/current application

using juju to maintain a current stack

  • new concepts: user auth
  • HA controllers
  • firewall management
  • block storage options

charm writing: new charms

  • “first minimal charm”
  • layers
  • reactive charms

charm writing: bundles

  • might be appropriate to explain how to use a bundle as a template for future deployments

Unfortunately, the state of Juju’s documentation is confusing. For charm writers, there is a lot of information spread around in several places:


#7

Hey Tim,

Thank you for your response,

I think all points you raised there are a really good start - I’m now trying to put myself in the just ‘juju’ head but they look like their in the right direction for juju users. My main issue was with writing charms themselves, and how that fits together with juju…

charm writing: new charms

“first minimal charm”
layers
reactive charms

This would be great with a flow similar to this:

  1. Juju local lxd cloud setup
  2. Write your own charm, hello world of course
  3. Juju deploy
  4. More advanced topics, maybe go into bundles etc.
  • As a note tensorflow.org and elasticsearch have great examples of these developer starter docs.

Unfortunately, the state of Juju’s documentation is confusing. For charm writers, there is a lot of information spread around in several places:

I’m also glad you’re aware of the charm docs being spread around the place - this is also a massive problem and in my honest opinion the charms and their docs need to be harmonised into a single place because it is extremely frustrating at times to find info on a charm.

Please if there’s anything I can help with let me know, as I really think juju is a great technology its docs just let it down!


#8

Hi @pjds, thank you for your feedback. I am part of the design team and I work on the user experience, so I find your point very interesting. Would you be available to answer to a few questions (we can send out a survey) and have maybe a chat with us in the future? User feedback is important to us, and you can help shaping the product.

Hi @timClicks, I think your proposal is great, how you broke things down is very clear and would help the users to navigate the content in a much easier way. I would like to set up a meeting with you also to keep you updated about the work we are doing around Juju and JAAS.

Thank you


#9

Sure, send it through.


#10

I have come back and had time to articulate my previous statements, so I guess what the ideal experience would be is something like this.

-> juju.jujucharms.com is where I go to get info on how to use juju, how it works, and so on.
-> charms.jujucharms.com is where I go for:

  • What are charms? Here we talk about the power of charming
  • How do they relate to juju? Here we talk about the power of repeatable deployments
  • Write your first charm
  • Other developer guides
  • Charm manual
  • Index of docs for published charms

I think this would offer an optimal experience to charming and help those who are new to the world of juju.


#11

Hi @pjds, thank you for your availability, we’ll get in touch soon.
About the domains, we are moving towards a simpler approach, removing our subdomains where possible (e.g. docs.jujucharms.com will soon redirect to jaas.ai/docs), but I think your feedback highlights the needs of a clearer organisation of content. We are working in that sense, and indeed the move from jujucharms.com to jaas.ai is in this direction: different websites for different audiences and purposes.