)]}'
{"/PATCHSET_LEVEL":[{"author":{"_account_id":36869,"name":"David Welsch","display_name":"Dave Welsch","email":"dw@cluemail.com","username":"dwelsch"},"change_message_id":"d68f0f88c02889d91c4b977e76e60e1621bb6ab8","unresolved":false,"context_lines":[],"source_content_type":"","patch_set":1,"id":"cb692af1_83f4daba","updated":"2024-06-21 19:46:23.000000000","message":"Glad to see someone is taking this on. I think this is a good first step to updating the ironic docs. My hope is that it will catalyze more changes, especially to the structure of the documentation.\n\nPart 1: \n\nI like the idea of reorganizing the admin guide. As I described in my analysis, I advocate organizing by information type (conceptual, instructional, and reference). In this case:\n- *Features* is conceptual\n- *Operation* is instructional (tasks)\n- *Architecture* is also conceptual\n\n... which suggests to me that Features and Architecture could be in the same section, or at least close together.\n\nI notice that on the [ironic doc main page](https://docs.openstack.org/ironic/2024.1/#), the Top-level Administrator Guide contains Drivers, Hardware Types, and Hardware Interfaces and then the Administrator\u0027s Guide. This is not how the Admin Guide is actually organized once you click it. Is there a reason it\u0027s different on the main page?\n\nPart 2:\n\nI agree with your logic for where to put these parts. I normally advise keeping reference information together (both the API and CLI ref here). But, you have a compelling reason to split them up (based on user role), so I\u0027ve got no beef with this. \n\nPart 3:\n\nAre you increasing or decreasing :maxdepth:? Increasing it will add context to each higher-level heading, but will also increase the length of the page, making it harder to navigate. I don\u0027t have any firm guidelines on what would be best. Maybe that\u0027s why you said you\u0027re going to play with it. :D\n\nI\u0027d preface all this information with a \"Where to Start\" section. The goal is to orient new users who come to the page. It doesn\u0027t have to be anything elaborate -- maybe it\u0027s a table or list of pointers to the best place to get information for different user goals, along the lines of \"If you want to ___, see ___.\" So for example \"If you\u0027re looking to use Ansible to install and run ironic, see the Bifrost documentation.\" And so on. You can refine this part later, maybe writing and pointing to a full-blown Getting Started guide eventually.","commit_id":"6495216361f2e85bb300bcabd661cf89ee0c8a94"},{"author":{"_account_id":10342,"name":"Jay Faulkner","display_name":"JayF","email":"jay@jvf.cc","username":"JayF","status":"youtube.com/@oss-gr / podcast.gr-oss.io"},"change_message_id":"e0c651faade3a1ff525460293a697babbdfa11f2","unresolved":false,"context_lines":[],"source_content_type":"","patch_set":1,"id":"4b9ddce2_e3eff6f2","updated":"2024-06-21 23:37:54.000000000","message":"JFYI, Dave, if you want to see the docs rendered, click the tab \"Zuul Summary\" or expand the comment where Zuul Verified+1, click the link to openstack-tox-docs, then go to the Artifacts tab, and click \"Docs Preview Site\" (I think the PDF is also published there; I\u0027m not sure I\u0027ve ever looked at it)\n\nFor the last commit, it was https://64164f103d25289fcf3e-cec36eea8e90c9127fc5a72b798cfeab.ssl.cf1.rackcdn.com/922484/1/check/openstack-tox-docs/b58f535/docs/\n\nThe rendered results stay up for 3-ish days depending on which CI host it\u0027s on.","commit_id":"6495216361f2e85bb300bcabd661cf89ee0c8a94"},{"author":{"_account_id":10342,"name":"Jay Faulkner","display_name":"JayF","email":"jay@jvf.cc","username":"JayF","status":"youtube.com/@oss-gr / podcast.gr-oss.io"},"change_message_id":"7eb76497d5a8c62b976dc7a3243f524e89306196","unresolved":true,"context_lines":[],"source_content_type":"","patch_set":1,"id":"dd655171_432a74e3","updated":"2024-06-21 23:38:29.000000000","message":"On my list to review this over the weekend.","commit_id":"6495216361f2e85bb300bcabd661cf89ee0c8a94"},{"author":{"_account_id":10342,"name":"Jay Faulkner","display_name":"JayF","email":"jay@jvf.cc","username":"JayF","status":"youtube.com/@oss-gr / podcast.gr-oss.io"},"change_message_id":"569989f091f53b522525660d03239d740291d79f","unresolved":false,"context_lines":[],"source_content_type":"","patch_set":1,"id":"6e4e3a9b_1672e015","in_reply_to":"cb692af1_83f4daba","updated":"2024-06-24 21:03:19.000000000","message":"My feedback mainly mirrors this, with an emphasis on two things:\n\n1) Features / Architecture really should be merged, and the top-level of that needs to be \"How does Ironic work\" with the high-level architecture information as suggested here\n2) A \"where to start\" section would be awesome, perhaps even linking out to kayobe/kolla-ansible/operator docs for people who want to install Ironic, and describing how to find information otherwise","commit_id":"6495216361f2e85bb300bcabd661cf89ee0c8a94"},{"author":{"_account_id":36869,"name":"David Welsch","display_name":"Dave Welsch","email":"dw@cluemail.com","username":"dwelsch"},"change_message_id":"5d8a548756a0444a5d0ef57481e527c817d474db","unresolved":false,"context_lines":[],"source_content_type":"","patch_set":1,"id":"5bea2d4c_7cda0dc3","in_reply_to":"dd655171_432a74e3","updated":"2024-07-04 17:08:37.000000000","message":"Done","commit_id":"6495216361f2e85bb300bcabd661cf89ee0c8a94"},{"author":{"_account_id":10342,"name":"Jay Faulkner","display_name":"JayF","email":"jay@jvf.cc","username":"JayF","status":"youtube.com/@oss-gr / podcast.gr-oss.io"},"change_message_id":"569989f091f53b522525660d03239d740291d79f","unresolved":false,"context_lines":[],"source_content_type":"","patch_set":2,"id":"169614cc_1780dda1","updated":"2024-06-24 21:03:19.000000000","message":"+1 because it\u0027s better than what is there, but I think there are potential improvements\n\nI\u0027m OK if this lands and we iterate","commit_id":"656f93b6e7a066c9a91150ecdd96ded4e6fad792"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"5e5249c3e81f7829b6515484961b5af97db71a97","unresolved":false,"context_lines":[],"source_content_type":"","patch_set":2,"id":"f076f740_509f99e9","updated":"2024-07-05 16:20:35.000000000","message":"For the reference: the traditional way to draw the line between users and admins was: a user is the one who deploys machine, an admin is the one who enrolls and configures them.\n\nToday, it makes progressively less sense. So our \"user guide\" should probably become more of a \"how to use the API\" guide: how to deploy, how to configure RAID, how to inspect.\n\nAs an aside, I\u0027ve always been confused on why OpenStack wants to have the installation guide separately from the admin guide.","commit_id":"656f93b6e7a066c9a91150ecdd96ded4e6fad792"},{"author":{"_account_id":36869,"name":"David Welsch","display_name":"Dave Welsch","email":"dw@cluemail.com","username":"dwelsch"},"change_message_id":"c1b2dfe617f470bfc88e04029b6ab499dba63dc5","unresolved":false,"context_lines":[],"source_content_type":"","patch_set":2,"id":"b32480cb_067b175e","updated":"2024-06-25 17:54:04.000000000","message":"I misunderstood what you meant by splitting the Admin guide -- I thought you were going to leave the Admin Guide as a top level heading and put the Features, Operation, etc. under that. A few thoughts:\n\n- I think your solution works just as well, maybe better than keeping \"Admin Guide\" (read the other bullet points below). But it implies a different organization hierarchy, so I\u0027d recommend careful thought into that hierarchy. I haven\u0027t explicitly emphasized user roles as much in ironic as I have in [other analyses I\u0027ve done](https://github.com/cncf/techdocs/tree/main/analyses). I came to the conclusion that user roles are similar in ironic and the differences are in the use cases (or at least that\u0027s a valid way to think of it). This organization fits that (use case-centric) model. \n- That being the case, I think it\u0027s even more important to group topics of similar type together; that is, instructional (installation, configuration, operation); reference (API, config ref, command ref); and conceptual (see Jay\u0027s comment about consolidating this information; I agree 100%). Right now, to a rough approximation, the Admin Guide is instructional and the User Guide is the conceptual info. That could mislead users unfamiliar with the existing version of the documentation.\n- An issue you need to resolve: If you do away with a top-level \"Admin Guide\", what does \"Admin Guide\" in the OpenStack doc portal point to?\n- Do you plan to similarly deconstruct the User Guide? (Wouldn\u0027t be a bad idea.) And if so, same question -- what does OpenStack\u0027s doc portal point to?\n- One solution would be to point the portal Admin and User links to landing pages (or indeed, it could be a single landing page) that explains that the \"Admin\" and \"User\" labels aren\u0027t particularly useful in ironic and maps out some destination pages based on overall task or use case (similar to the suggested Getting Started task map on the landing page). I pointed out in the analysis that OpenStack\u0027s portal structure is a one-size-fits-all solution that might not exactly fit ironic, and this seems more and more to be the case as we proceed here.","commit_id":"656f93b6e7a066c9a91150ecdd96ded4e6fad792"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"194f2208c2fc6b7eeb0eb4f1066d855725c3a7f6","unresolved":false,"context_lines":[],"source_content_type":"","patch_set":2,"id":"82c0f32a_9f72438b","updated":"2024-07-05 16:16:22.000000000","message":"Thank you for your feedback Dave!\n\n\u003e which suggests to me that Features and Architecture could be in the same section, or at least close together.\n\nOur Features section is, to a large extent, use-case driven and instructional. This is why I grouped them the way I did.\n\n\u003e Is there a reason it\u0027s different on the main page?\n\nYeah, I did it looong ago to highlight the drivers because otherwise they\u0027re buried too deep, and users/operators often needs driver-specific information.\n\n\u003e Are you increasing or decreasing :maxdepth:?\n\nI have a habit to increase :maxdepth: because I like having an overview of what I can find in the documentation. You mentioned in your review that it\u0027s not always easy to understand where to look for information. This is my usual struggle on documentation pages that only have 5-6 top-level links. I\u0027m open to your opinions of course!\n\n\u003e I\u0027d preface all this information with a \"Where to Start\" section.\n\nA good call, agreed.\n\n\u003e An issue you need to resolve: If you do away with a top-level \"Admin Guide\", what does \"Admin Guide\" in the OpenStack doc portal point to?\n\nIn some ideal world, an admin guide would describe how to install/configure/upgrade Ironic, while the user guide would describe how to use our API. We\u0027re not great at this distinction, unfortunately.\n\n\u003e Do you plan to similarly deconstruct the User Guide? (Wouldn\u0027t be a bad idea.) And if so, same question -- what does OpenStack\u0027s doc portal point to?\n\nWe need to. But we need to have a final agreement on who the User is and what they are up to.\n\n\u003e One solution would be to point the portal Admin and User links to landing pages (or indeed, it could be a single landing page) that explains that the \"Admin\" and \"User\" labels aren\u0027t particularly useful in ironic and maps out some destination pages based on overall task or use case\n\nThat\u0027s a completely new but actually very good idea.","commit_id":"656f93b6e7a066c9a91150ecdd96ded4e6fad792"},{"author":{"_account_id":10342,"name":"Jay Faulkner","display_name":"JayF","email":"jay@jvf.cc","username":"JayF","status":"youtube.com/@oss-gr / podcast.gr-oss.io"},"change_message_id":"e8a23c43b9600c86738cd53bbd45f08041799422","unresolved":true,"context_lines":[],"source_content_type":"","patch_set":2,"id":"c39d8f0b_e99fabd7","updated":"2024-07-04 16:36:43.000000000","message":"This is better, we should land it and iterate.","commit_id":"656f93b6e7a066c9a91150ecdd96ded4e6fad792"},{"author":{"_account_id":10342,"name":"Jay Faulkner","display_name":"JayF","email":"jay@jvf.cc","username":"JayF","status":"youtube.com/@oss-gr / podcast.gr-oss.io"},"change_message_id":"2bfedf24200602626c6821b9bfb5bc2a33bbf928","unresolved":false,"context_lines":[],"source_content_type":"","patch_set":2,"id":"6585e97f_c31f6f7a","in_reply_to":"b32480cb_067b175e","updated":"2024-07-04 16:45:01.000000000","message":"\u003e One solution would be to point the portal Admin and User links to landing pages (or indeed, it could be a single landing page) that explains that the \"Admin\" and \"User\" labels aren\u0027t particularly useful in ironic and maps out some destination pages based on overall task or use case (similar to the suggested Getting Started task map on the landing page). I pointed out in the analysis that OpenStack\u0027s portal structure is a one-size-fits-all solution that might not exactly fit ironic, and this seems more and more to be the case as we proceed here.\n\nThis is an exceptionally good idea, and something I hadn\u0027t thought of before. I might play with this once dtantsur\u0027s first two patches here land.","commit_id":"656f93b6e7a066c9a91150ecdd96ded4e6fad792"},{"author":{"_account_id":36869,"name":"David Welsch","display_name":"Dave Welsch","email":"dw@cluemail.com","username":"dwelsch"},"change_message_id":"5d8a548756a0444a5d0ef57481e527c817d474db","unresolved":false,"context_lines":[],"source_content_type":"","patch_set":2,"id":"ce24fec3_cca31ccf","in_reply_to":"c39d8f0b_e99fabd7","updated":"2024-07-04 17:08:37.000000000","message":"Acknowledged","commit_id":"656f93b6e7a066c9a91150ecdd96ded4e6fad792"}]}