[DOCS] - "Outdated" files (38/250) #2177
Comments
|
Issue-Label Bot is automatically applying the labels:
Please mark this comment with 👍 or 👎 to give our bot feedback! |
|
@8bitmp3 @jlewi @Bobgy @joeliedtke @rmgogogo I compiled this list of outdated docs. I did this 3 days ago, but only thought of pinging you now. Let me know how we can effectively tackle this issue 🚀 |
|
Thanks Rui. Would you share how to check it's "outdated" here? I may have less knowledge on it. Do you mean compare it with the website and website doesn't have the latest content in Github? |
|
Thanks @RFMVasconcelos Can we identify the owners for the relevant docs and file issues for them to update the docs? Maybe you can automate the opening of GitHub issues using the GitHub CLI/API? For locations with outdated or no OWNERs files can we try to track down the appropriate owners or WG? |
|
@cspavlou @kimwnasptd @andreyvelich @james-jwu HI All, it appears that the docs are out of date for several components. Can we please try to get those updated by the end of October ? |
|
cc fyi @RFMVasconcelos @alfsuse @Jeffwan @neuromage @numerology @vpavlin @crobby @pdmack @shawnzhu @adrian555 @Tomcli |
how about update the list @RFMVasconcelos put together with the owner's name for each page? This way we will know who is working on what. One important point I think we should pay attention to the sections root pages.. those shouldn't be deleted in any case for the Workstation sections, I may work on the minikube pages and general ones. |
Updated List - 106 out of 250 docs files are "Outdated"Split by section:
|
|
@jlewi @8bitmp3 @jbottum please find above the updated "outdated docs" list, by section of the website.
WDYT? |
|
A relevant thread about the Upgrading section from #2257 (comment) by @jlewi
@jlewi If you're OK with removing the whole section, we can do that (cc @RFMVasconcelos ). Then we together with OWNERS of each of the "subprojects" (AWS, IBM Cloud, Azure, Pipelines, etc) can start adding an From OWNERS files:
Other components... |
|
I like the idea of regularly reviewing our docs, but I’m concerned that tagging each doc as outdated creates unnecessary toil for docs contributors. Are there any other docs projects that you know of that use this strategy? If so, what was their experience like? WGs should be updating docs as a part of their work. This leads me to wonder, how much of the docset is expected to go stale with each release? If the WGs are updating their docs, then only a small portion of the docset should reasonably break in a release. Assuming that this is correct, the time spent checking docs may not feel worthwhile for contributors since they may test many pages without finding an issue. Testing a document like a tutorial is resource intensive. If contributors are asked to commit time to a task that does not seem sufficiently impactful, they may not participate or they may work around the system. (By writing a script to remove the tag.) Perhaps we should address this issue in two ways. First, get each WG to review their docs once to verify that they currently have docs that work as expected. Second, going forward we could surface information to get reactive participation from the WGs. We could provide a report that links docs bugs to docs, so owners can respond to user feedback. We could also look at setting Kubeflow.org up to automatically add a “This page might be broken” link to docs with open issues. These links could open a GitHub issues query filtered to that doc’s issues. That approach gives users insight into what may be broken, and ensures that WGs are aware of the issues that are reported for their docs. What do you think? |
|
Can somebody explain how docs that were written for Kubeflow 1.1 (feature store) are flagged as outdated? They shouldn't even be visible in 1.0 and yet that is what the pages now show. |
|
/reopen |
|
@PatrickXYS: Reopened this issue. In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
|
Thank you so much for your awesome feedback @joeliedtke
💯% @joeliedtke 👍 👍 👍 What are your thoughts @PatrickXYS@adrian555 @animeshsingh @Tomcli @IronPan @numerology @neuromage @alfsuse @Jeffwan @Aronchik @shawnzhu @rmgogogo @cliveseldon @knkski (and many more 😃 ) ? Hi @woop! I think the docs were flagged as "outdated" during the v1.1 docs transition. Check out @jlewi and @RFMVasconcelos 's comments here: #1984 (comment) and #1984 (comment) I hope this helps! |
I think we should put in place a process where each WG before any new release takes a review in advance so we know upfront which page needs to be re-worked and which not. Also on another note: |
|
Regarding adding a documentation lifecycle, that may be a good question to discuss in a community meeting. My initial thought is that we probably don't need full documentation reviews for minor releases. A full review may be more appropriate for a major release, since there is more potential for a breaking change. |
|
Is seems we're now at 50 outdated pages - list below: |
rui-vas
changed the title
|
cc @kubeflow/wg-training-leads |
|
@RFMVasconcelos do we have an updated list of which are still marked "out of date", as this looks bad |
|
@thesuperzapper we are now at 38 files! The list now is: |
rui-vas
changed the title
|
@thesuperzapper you can track this list with the command:
|
|
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions. |
|
There are still many pages under "components" which have "outdated" headers, we should clean these up. |
|
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions. |
|
it seems this issue was resolved. @rui-vas let us know if you are still seeing any issues otherwise this issue will be closed. |
|
@thesuperzapper are you still seeing any issues on this? issue will be closed by the end of the month if there are no new activities. thanks! |
|
@varodrig I dont see any more cases of this banner, we can close. /close |
|
@thesuperzapper: Closing this issue. In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
Below is a list of all the outdated files on the docs today.
There are 120 files with "Out of date" out of the 250 files under /content/en/docs/:
The text was updated successfully, but these errors were encountered: