Feedback: entirely missing Kinect 1.8 SDK docs, needed for legacy support and future historians

[diablodale]

https://docs.microsoft.com has no content for the first-generation Kinect sensor. Which uses the Kinect for Windows SDK 1.8.

This SDK and its runtime are readily available for download from Microsoft. However, the SDK documentation has recently been purged. Its return is needed.

Problem:
Kinect v1 aka original Kinect for Windows aka first-generation Kinect content missing. Please note, SDK 2.0 is available but that SDK works on the second-generation Kinect. Completely different hardware and completely incompatible. Therefore, the Kinect for Windows SDK 1.8 is completely distinct and separately needed.

This is a symptom of the Great Darkening. Technology moves forward, yes. However, the archive of documentation for technology is needed for both technical use, backward compatibility, forward compatibility, legacy support, and for future historians/museums. I can appreciate that you have limited resources to update content. Great. Then take the Kinect for Windows SDK 1.8 content, print to PDF, and make that PDF available.

Unfortunately, the waybackmachine doesn't have a working snapshot that I have found. For example, the links to reference docs on this page fail https://web.archive.org/web/20150905084124/https://msdn.microsoft.com/en-us/library/hh855347.aspx
yet I was able to get some others at https://web.archive.org/web/20130526051655/http://msdn.microsoft.com/en-us/library/nuisensor.nuicreatecoordinatemapperfromparameters.aspx

[welcome[bot]]

Thank you for creating the issue! One of our team members will get back to you shortly with additional information.

[supernova-eng]

Adding @jemash to help investigate what happened to the linked content.

[gyurgyma]

Has there been any update on these docs? I also would like to have them restored or have a pdf to work with.

[norlesh]

Adding an extra voice to the issue... Who deletes docs when the API is still being distributed anyway???

[andresantacruz]

So sad this issue hasn't yet been fixed :/

[AJAbanto]

Still waiting for those docs, I hope this gets resolved soon

[KulaGGin]

Yes, give us full documentation. Just because you stopped producing it and selling it doesn't mean you have to kill the docs. It's just text, it's not like you're out of bytes.

[Chrisvb99]

I am currently working on a project using a first generation Kinect and cannot find any SDK v1.8 documentation. Do I have to assume that v2.0 is the same??? Unbelievable that I cannot easily find it with a simple google search.

[diablodale]

@Chrisvb99 , 1.8 is completely different than 2.0. The APIs are incompatible and you can't use similar coding.
Without 1.8 API documentation, your project will be very challenging.
@Jemash , would your team please publish a PDF of the docs? Please stop the "Great Darkening"

[norlesh]

And now to add to the issue Microsoft has started expunging the 2.0 API documentation!!!
What the BLEEP is wrong with just including the documentation inside the SDK since Microsoft obviously can't be relied upon for archival.
....
Assuming this page for the : CoordinateMapper class hasn't been removed, following the link to documentation for GetCameraIntrinsics ends in a fail

[diablodale]

I can also reproduce the failures in the SDK 2.0 documentation on the en-us site
https://docs.microsoft.com/en-us/previous-versions/windows/kinect/dn772971(v=ieb.10)
click "GetDepthCameraIntrinsics"
results in:
"Unable to Service Request"

[Jemash]

I did not see this issue assigned to me. I am looking into it now

[kexugit]

We are working on moving the missing content to docs.microsoft.com. Thank you for your patience.

[kexugit]

Kinect for windows sdk 1.8 has been added back: https://docs.microsoft.com/en-us/previous-versions/windows/kinect-1.8/hh855347(v=ieb.10).

[diablodale]

Thanks for the progress update. I clicked randomly in many sections of SDK 1.8 and I see content. 🙂

Open items of which I'm aware:

• Kinect SDK 2.0 docs. The docs currently online are corrupt. e.g. https://github.com/MicrosoftDocs/feedback/issues/1214#issuecomment-587544049
• Download of the Kinect SDK 1.8 and 2.0 for offline use, long-term reference for customer solution fixes/updates, archiving, etc. I don't see the 'Download PDF' link at the bottom-left that appears on the Kinect Azure (v3) online documentation.

[gyurgyma]

It seems to me that the whole C++ reference is still missing. Going to any of the subsections of the C++ reference here take me to a permanently redirected page: https://docs.microsoft.com/en-us/previous-versions/windows/kinect-1.8/hh855364(v%3dieb.10)

[diablodale]

@gyurgyma , thanks for surfacing that issue. I didn't notice that in my casual testing.

Can you find the C++ docs in the sibling sections? Meaning...rather than starting at the link you gave for C++, instead start at NUI, Face Tracing, or Dev Kit and then drill down to the C++ interfaces? e.g. https://docs.microsoft.com/en-us/previous-versions/windows/kinect-1.8/hh855366(v=ieb.10)

[kexugit]

PDF download has been enabled and is available for both 1.8 and 2.0 SDK. The missing topic you are seeing (GetDepthCameraIntrinsics method) might be trickier and is being looked into.

[gyurgyma]

@diablodale, yes, it looks like I can simply drill down into it. I'm not sure how I didn't manage to figure that out. The PDF also looks to be complete and can be utilized for what I need. Thanks for pushing on this over the last year. Hopefully in time, it gets fully restored.

[kexugit]

@diablodale The missing topic has been added: https://docs.microsoft.com/en-us/previous-versions/windows/kinect/getdepthcameraintrinsics. This should complete the resolving of the issues you reported. Please let us know if this can be closed now. Thanks!

[norlesh]

It's great that the content is accessible once more - the ideal fix to the originally posted problem would however be to make http://go.microsoft.com/fwlink/?LinkId=280210 (the SDK Documentation link installed by the SDK installer) resolve to the 1.8 SDK docs or at least provide a link on that page since otherwise your fix wont be found.

[diablodale]

@kexugit hello. I randomly checked some content in the 1.8 and 2.0 SDKs your team uploaded. I found the following. I do appreciate your team returning the content. Personally, it doesn't have to be perfect as long as the content is there somewhere 🔍🙂 Because the below are so methodical/regular, I suspect this is a code/transform issue that if resolved will fix globally these issues.

Duplicate left nav nodes, the upper duplicate has invalid links

1. visit https://docs.microsoft.com/en-us/previous-versions/windows/kinect/dn782039(v%3dieb.10)
2. Visually notice in the left navigation, there are two entries "Known Issues".
3. Click the link in the right content "2.0 SDK and Developer Known Issues"
4. You will get an error
5. Click back on your browser
6. In left navigation, click "2.0 SDK and Developer Known Issues"
7. I successfully see the content

This same pattern repeats in content

1. visit https://docs.microsoft.com/en-us/previous-versions/windows/kinect/dn782038(v=ieb.10)
2. Visually notice in the left navigation, there are two entries "Reference"
3. Click the link in the right content "C++ Reference"
4. You will get an error
5. Click back on your browser
6. In left navigation, click "C++ Reference"
7. This becomes a recursive scenario...
8. Click the duplicate child in the left nav "C++ Reference"
9. Click the link in the right content "Interfaces"
10. You will get an error
11. Click back on your browser
12. In left navigation, click "Interfaces", then its duplicate child "Interfaces"
13. I successfully see the content

Duplicate content in PDF

1. Visit https://docs.microsoft.com/en-us/previous-versions/windows/kinect/dn799271(v=ieb.10)
2. Click 'Download PDF' link at bottom-left
3. Find the second occurance of IAudioBeam Interface. It should be the IAudioBeam Interface section on page ~150
4. Notice the content in this section. It has duplicate Methods sections - each with duplicate methods.

Links inside PDF link to live website, instead of linking to content in PDF

1. Continue from the repo directly above
2. Click the first method in the section get_AudioBeamMode
3. You will be sent to the live website. I prefer instead that link go to the method's section within this PDF document (approx page 153)
4. This problem of links going to the live website is throughout the PDF.

[kexugit]

@diablodale The broken links and duplicated methods that you reported have been fixed.

The duplicated TOC nodes are by-design: we want to avoid a single TOC node being used for both a expendable parent node, and a node with link. In this case, e.g., the "Known Issues" node served as a parent node with a link on MSDN. When migrated to docs.microsoft.com, it became two TOC nodes: an expandable parent node without link , and another child node with link, both sharing the same name.

For the links inside PDF that point to live site, I understand that you prefer in-file links, but unfortunately I don't think we have the resource to improve that at this time. During migration, we preserved the full URLs inside the topics. However, in order to enable in-file links in PDF downloads, those links have to be converted to the relative path of the corresponding markdown source files. The amount of updates required across all migrated content is not something we could accommodate at this point.

@norlesh we are working on updating the fwlink you reported: http://go.microsoft.com/fwlink/?LinkId=280210. It will be updated to point to the landing page of 1.8 SDK documents.

[diablodale]

@kexugit, great...and got all you wrote.

I found two issues in the v1.8 docs PDF download

Missing Section title/headers

Repro

1. Visit any webpage in the v1.8 docs, e.g. https://docs.microsoft.com/en-us/previous-versions/windows/kinect-1.8/dn435682(v=ieb.10)
2. click the 'Download pdf' at the bottom-left
3. Look at many pages of the PDF across multiple sections

Result

Thoughout the v1.8 PDF download, the blue section headers are empty with only minutes to read. There is no section name, no number of minutes, etc.

Expected

Section names/titles. Personally, I don't need the number of minutes.
Given links within docs don't function, can this issue be resolved so that we can better scan and text-search through the doc?

Missing Content

Repro

1. Visit any webpage in the v1.8 docs, e.g. https://docs.microsoft.com/en-us/previous-versions/windows/kinect-1.8/dn435682(v=ieb.10)
2. Click the 'Download pdf' at the bottom-left
3. Visit any of the following webpages, and their corresponding page in the PDF
   https://docs.microsoft.com/en-us/previous-versions/windows/kinect-1.8/hh855674(v=ieb.10)
   corresponding PDF page 1237
   https://docs.microsoft.com/en-us/previous-versions/windows/kinect-1.8/hh855409(v=ieb.10)
   corresponding PDF page 1167
   https://docs.microsoft.com/en-us/previous-versions/windows/kinect-1.8/jj131069(v=ieb.10)
   corresponding PDF page 1172-1173

Result

Missing content on the webpage and the corresponding PDF page. Seems a repeating pattern of a class of content. The first link above is interesting in that there are sometimes 1, sometimes 2 missing pieces of content on each line. I suspect these are images that have text of "public", "static", or "property/member".

More examples where these are missing in the PDF on pages 1262, 1279, 1284, 1286, 1293
It's hard to find the matching webpage...because the section titles are missing ;-)

[kexugit]

@diablodale will look into fixing the issues you reported.

@norlesh the fwlink you reported has been fixed.

[kexugit]

@diablodale The PDF issues you reported have been fixed. The missing content you were seeing were just icons, but they are also added back to the web pages and PDF files now.

[diablodale]

Thank you. I don't have any content concerns with v1.8 or 2.0 docs at this time.
Anyone else have webpage or PDF content concerns?

[Jemash]

Thank you all for working through this with us!
@kexugit can this be closed now?

[kexugit]

Thank you all for working through this with us!
@kexugit can this be closed now?

Yes. But I don't seem to have permission to close it.