carvel-dev
Couldn't find a field in "Configuration" docs
What steps did you take:
During the TGIK session, while attempting to build with Docker, Josh Rosso was looking up the meaning of a field (path) in the configuration in the docs.
What happened:
He couldn't find it without the help of a Carvel team member. He scrolled immediately down to the "Docker" section... and looked for the definition of path (which is actually part of Source)... but that wasn't listed there.
What did you expect: I expected he could have easily located the meaning of any field in the configuration schema.
Anything else you would like to add: It seemed to be unclear that each subsection in this page describes an inner portion of the configuration file.
Possibly, if that hierarchy was more obvious (e.g. a link to jump up to a higher level), Josh might have gotten there.
Part of me thinks this can be solved if someone does a cmd + f or ctrl + f on the page to find the information. It's the second mention of path on the page in this case.
Possibly, if that hierarchy was more obvious (e.g. a link to jump up to a higher level), Josh might have gotten there.
Any further thoughts on this? Is the suggestion to move schema definitions under each section on the page (e.g. path under the Sources section)?
Any further thoughts on this? Is the suggestion to move schema definitions under each section on the page (e.g. path under the Sources section)?
I was thinking that including all the keys in each example, and then linking fields to where they have already been explained (such as path), would convey the hierarchy and provide the user with the info they need at any point in the page.
Do we think this is still an issue now that the search feature is live? When looking for path in the kbld docs, it points to Configuration -> Schema and Configuration -> Sources, which would both point to the right place.
I see your point, @StevenLocke.
However, the original issue has to do with how clearly this reference is (or isn't) clearly presenting the whole structure of Config to a person merely reading the page.
Any further thoughts on this? Is the suggestion to move schema definitions under each section on the page (e.g.
pathunder the Sources section)?
Yes:
- In the YAML document under "Schema", show the entire document, including optional fields to help connect the top-level structure with each of the optional sub-trees
- right under that snippet, only describe the top-level fields and then include links to each of the sections (i.e. "Sources", "Destinations", "Overrides")
- within each section (e.g. "Sources"), describe its top-level fields.
- in each sub-section (e.g. "Docker"), use ellipses (i.e.
...) at the top of the document to indicate there's more above it and just include the fields being elaborated on - describe each sub-section as "one of (Section)" and make that section name a link to that Section. (e.g. "
docker is a kind of [source](#Sources)")
I think that the approach that @pivotaljohn outlined will be helpful. This would lower the amount of repetition we have, where we define the list of sources possible twice, and also provide better visualization of the Configuration.
Accepting this story to implement the above suggestion from John.
When implementing this issue we should look out for other points in the kbld where we do something similar and improve the documentation in those spots as well.
