NightOwl888 commented on issue #396: URL: https://github.com/apache/lucenenet/issues/396#issuecomment-786962763
Per @Shazwazza, when I asked him via chat whether it is now safe to update the documents with .NET-specific content: > Yes it is safe to modify the .md files now with .NET content. In some cases however, it is more safe to use docfx 'override' files. For example, we are already doing this with the [/websites/apidocs/apispec/core/Lucene_Net_Codecs.md file](https://github.com/apache/lucenenet/blob/0dbda3e18c7b69bd6beecd8e47d288c00d5d5440/websites/apidocs/apiSpec/core/Lucene_Net_Codecs.md). This is 'overriding' the default converted namespace file at [/src/Lucene.Net/Codecs/package.md](https://github.com/apache/lucenenet/blob/0dbda3e18c7b69bd6beecd8e47d288c00d5d5440/src/Lucene.Net/Codecs/package.md) . In some cases it may make more sense to use override files as opposed to modifying the converted file. I guess there's no strict rules on whether to use override files or not. I dunno, i guess there's pros/cons to both. By changing the converted files it means we'd know about any changes made upstream to them in the Java Lucene project and we'd have to manually merge those, but by using override files we don't end up with merge issues which might be nicer in cases where we totally overhaul the docs. It sounds like override files are probably better for maintenance. But on the other hand, it sounds like it might be confusing for contributors if they think that modifying the original will modify the API site. We should probably do an experiment with each to try to get a feel for which choice is the right one for given scenarios. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
