Restructure for IIS docs#19987
Conversation
|
Dashes in the file names won't matter nearly as much as the content for SEO, but the recommendation is for dashes and these match our usual pattern ...
I ordered the original sections based on my usual general-to-specific and step-by-step writing guidelines. When you reach the stage of setting up the ToC for these later, you should be able to at least start with ordering of the topics on the basis of the order of the sections in the current topic then tweak it further from there. Fortunately, there are only 24 cross-links to the index.md topic. Of those, only ten link to a specific section. I recommend checking all 24. Hopefully, only ten or fewer links will require an update. |
|
@guardrex thanks for the feedback. Question for you, I noticed that we have a doc called Publishing To IIS which shares a lot of information in main doc about publishing in the overview doc. One of these is more of a brief overview while the other is more indepth. I think having a simple doc makes sense for getting started, however I don't want to lose some of the info here as well. |
|
Yes, that tutorial came directly from reader feedback. Many weren't happy with the BOOK that we had here on the subject ... even getting lost in the forest of configuration. Therefore, we added this base case IIS tutorial to get up and running with a lot of defaults. I recommend keeping it. It gets very little negative feedback/questions. |
|
Do you recommend keeping both tutorials? My other thought was to remove the more verbose tutorial and have that in subsection for advance material (like web deploy details, process bitness, etc). |
|
IIRC, the main doc that has the section was probably left in place because there were some differences ... I thought that there might be a tiny bit more detail than in the newer Pub to IIS tutorial, where I tried to say as little as possible for the base case. If u think that section can go away leaving the tutorial, that seems fine. I suggest comparing carefully tho before chopping it out in case my hunch is right that it has a tiny bit more detail that should either be added to the Pub to IIS tutorial (less favored) or remain somewhere in other docs of this node (more favored) ... as u just suggested. Keeping that tutorial as light as possible is probably a good goal. |
|
FYI from the build report |
|
@jkotalik ... 😕 ... Don't we want to leave the versioning as-is? 2.1 is supported until August 21, 2021. |
|
@guardrex a few things.
|
|
Ok ... I thought you were going to pull the content from the overview. I guess not ... if that existing overview content (that's showing up in the new 5.0 topics) will just be versioned <5.0 in the overview topic, then I think 🤔 this will go well. There would be a concern about maintaining multiple copies of the same content across docs. It's more 💰 costly 💰 to do it this way if docs change; however, these docs have been so stable over the last two years that I think this approach will be fine and not be a major 🕐 and 💲 drag. The 🙏 bean counter gods 🙏 will ❤️ me for keeping such things in mind! 😄 lol |
|
btw -- wrt the breaking link point ... that's going to happen anyway. When this group of docs drops 3.1 (in the distant future), existing links to the prior content in the existing overview will need to be updated. I think it's about ten links, so it's no huge deal. If these changes were being done without the duplication, such a future change would be automatically covered. |
jkotalik
changed the title
|
I think this is ready to pass of to the doc team; content and structure are there now. Few things that are left over:
|
|
Cool ... I'll take a look first thing tomorrow morning. |
|
🥂 |
|
ei ei ei ... I'm at the DMV 🚗 ... and you know how that goes! 😖 Give me a few hours. I'll review as soon as I get back. |
|
I'm back! ... and I was only at the DMV for two hours. 😩 Glad that's over with. I'll make an edit pass directly, then I have a comment about the file locations to post to you. |
guardrex
left a comment
guardrex
left a comment
There was a problem hiding this comment.
Ok ..... whew 😅 ... that was a lot of content to go thru. Most of my updates were for localization. We're code-fencing a lot more these days (e.g., paths, file and folder names, API, etc.) to avoid MT.
WRT file locations ... just letting you know as an FYI ... the ANCM topics were placed in the host-and-deploy folder because they apply to both IIS and Azure topic sets. Therefore, they were placed up a level from those nodes. I don't think there are any changes for the PR. Just letting you know why that was the case.
WRT image links ... I can't see the internal build topics, so someone should 👁️ them to make sure static image links are ok. I think they'll be fine.
You have a few 'make a bullet list here' remarks in there.
I'll approve now and probably take one more quick look tomorrow (Thursday) morning.
|
... and check the build report. There are build errors to address. |
|
kk ... Performed another round of localization updates. There's even more that could be done for older versions, but let's not take those updates any further. The 2.x content will go away next year. I did run thru and try to get all of the XREF asterisks out in all versions in favor of |
|
ok ... truly ....... 😄 ... there's a lot of content here. I'm sure nits will be missed. Except for the build report items, it should be ok†. †'It should be ok.' — Put that on my tombstone plz! ⚰️ |
|
Looks like the ANCM topic and the old tutorial (and any others that were moved or deleted) will need redirection entries ... https://github.com/dotnet/AspNetCore.Docs/blob/master/.openpublishing.redirection.json ... and existing redirect entries (if there are any) in the file can be updated to prevent multiple redirects from ancient links. |
|
... and there are still build report errors. 💥 |
|
Line 963: [Warning] Invalid file link: 'index/_static/ANCM-502_5.png'. |
jkotalik
force-pushed
the
jkotalik/updateTroubleshootingGuide
branch
from
feb5103 to
53983f6
Compare
|
That was my bad if it was breaking. MT will do things like take "web.config" and try to translate the word "web" leaving it a broken file name. You did the right thing. |
|
@guardrex @Rick-Anderson I think this is in an OK state. As this is such a large change, what are the next steps for getting this merged? |
|
I still don't see redirect file entries here, and I think two or more are needed. |
|
I don't know what those are or how to fix them 😅 |
|
Did one topic disappear and at least one more totally move (i.e., it's folder location changed, so it's URL also changed)? We need redirect changes so that the old topics don't 404 but redirect to elsewhere (or the new topic URL) ... https://github.com/dotnet/AspNetCore.Docs/blob/master/.openpublishing.redirection.json |
|
oh ... one more thing on that ... there are probably earlier redirects already in the file that point to what are now the old locations of topics based on this PR. Therefore, it's not merely a matter of adding two (or more entries). The file has to be searched and updated for any earlier redirects that were sending traffic to the prior locations, too. |
|
I don't believe any files should have moved; I only added files and changed content in existing ones. If you can point me to the ones that need redirecting, I can fix them. But not sure which ones 😃 |
|
oh ... ok ... false alarm then. IIRC, it was some earlier commit that I thought I saw something be deleted. The current PR seems good. We can check the live topics as soon as this goes in to make sure that everything composed well. The build report seems ok. @Rick-Anderson ... do u want to take another look? If not, I think it's good to go. |
|
Yeah, I'm going to continue to follow up with the restructure with new docs. |
3 participants
Fixes #19982
None of the docs are finished yet, but contains the general structure I'm aiming for.