created a more thorough overview for devfiles #28
Conversation
|
@rkratky, thanks for the review. I've made a new, squashed commit. @elsony and/or @johnmcollier, thorough enough overview do you think? |
|
@johnmcollier, thanks! New and squashed commit is up. Would you please comment with @rkratky, once it has the |
There was a problem hiding this comment.
A couple of things that I'd like to add to the overview:
- Includes some concrete examples of things that can be included in the devfile, e.g.
Includes:- Guidance about runtime images
- Example code
- Build and CI commands
- Deployment options
- Add who can use devfiles (stack providers, tools provides, developers)
|
@elsony, thanks for the review. See the new, squashed commit, addressing your feedback. So, I added context to our As far as including example code, commands, guidance on runtimes, and deployment options, were you thinking of taking some content from elsewhere in our docs? Going through the devfile docs we have, I didn't see anything that instantly spoke to any of these topics you suggested. So thoughts on how we'll get this content to users on this overview page? |
@jc-berger Sorry, maybe I wasn't clear on my initial comment. I only meant to include that list of 4 things (just those 4 entries) as part of the overview docs as the intro. The user can find the actual details of those from our user guide and schema doc. |
|
@elsony, thanks for the feedback. I was on vacation when you did your review, hence, the late reply. The new commit is up. I like your idea of making the sections of the doc a bigger size, comparable to the title's font size. However, throughout the rest of the doc, each section is simply emboldened, not actually a bigger font size. So to be consistent, I left these section titles bold, not making them bigger. As we continue to improve our docs this year, the doc team can discuss how we want to organize our sections! Let me know what you think of the changes and if you think it's ready to merge. Thanks! |
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: elsony, jc-berger, rkratky The full list of commands accepted by this bot can be found here.
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
|
Hi Jake, thank you for a great and well-written text. |
|
New changes are detected. LGTM label has been removed. |
|
@ossontoes, awesome, on point revisions and feedback :) I completely agree about there being too much noise and too complex grammar. I've addressed your comments. Please let me know what you think, thanks! |
|
@elsony, I'm thinking about the links in our "additional resources" section. From a doc perspective, links can be troublesome: they can become outdated, encourage users to quickly leave the page, etc. I do like directing users' attention after the overview. But instead of giving several links, maybe only one link to the rest our documentation? What do you think? If you like the idea of cutting down the "additional resources" section, let me know, and I'll get a new commit so we can see how it'd look in the final version. |
|
LGTM, thank you @jc-berger |
|
@jc-berger How does it look like if there is only one link? Can you provide an example? If you don't want to keep multiple links, I am fine with not having this link as part of this PR and handle it in a different PR. |
minor changes to sentence structure changed sentence structure added context to additional sources and who can use devfiles added more context improved grammar and removed passive voice and noise removed unneeded period
jc-berger
changed the title
For issue #159
I've applied the comments and feedback from the previous PR, [#25 ]. Due to doc restructure, it was easiest to close out that PR and branch and start anew.
@elsony and/or @johnmcollier, tagging either of you to see if this new content is thorough and extensive enough for a solid overview on devfiles for users.
@rkratky, tagging for your awareness as well.