First, let me say that I notice this bug mostly when working with the document API.  I assumed it was something related to my code, but I have been able to replicate this in the Umbraco backend, so I think it is a legitimate bug.  I can't say that this is the same exact issue that I see when dealing with the API, but it does have the same symptoms.

The problem is when a published content node ends up with a "link to document" value of "#".  This behavior can be reproduced by unpublishing a parent with published children, then publishing the parent.  The child will have an invalid link to document and will not be viewable on the front end.

I have seen a couple people discuss similar issues related to the "link to document" on the forum and the generally accepted response to resolve this is to call http://YOURDOMAIN/Umbraco/dialogs/republish.aspx?xml=true and click "republish".  While this does work to resolve the problem, you would first have to notice that a page has an invalid link to document (which usually happens because a client complains that front end content is missing).  Since the issue manifests itself for me while using the API, I can't determine easily that something has gone wrong creating the document link.

Here is a link to someone experiencing the same issue I describe.  http://our.umbraco.org/forum/developers/api-questions/20507-Create-and-Publish-document-in-API. 

Any insight that you can provide owuld be greatly appreciated since this issue has been plaguing me for months on 2 different client sites.

Thanks in advance!

--Mike