Repository navigation
Migration of Code Documentation #160
Description
There have been many questions both in issues and PRs that could have been addressed with some existing as-yet unmigrated documentation. (Not all questions, but a significant number.) People are curious, that's great.
Note that this is not MSDN-style API documentation, but more ad hoc documents. I believe there is a shared understanding that documents like this, not MSDN-style docs but the more ad hoc docs, should be checked in next to the code. Let me know if not.
This will not be a straight copy job though and should be done with due care, for the following reasons:
- some docs refer to the prior internal name for ML.NET (though to be fair I've noticed the code does too in places 😛) so that ought to be changed,
- it appeals to historical perspectives or prior states of code that are invisible to people, which is awkward. This is hard, you can't just delete that stuff, because the point of the code docs is to explain exactly why something is engineered in a certain way, and that discussion is helped enormously if you explain why a deceptively "easier" way of doing task X, Y, or Z was deemed unacceptable.
- it sometimes contextualizes the presence of this or that aspect of the code as being something that exists to solve an existing use-case, and not all those use-cases are open sourced.
- While much of it is already in
.md, some older docs are in other formats and will require some attention to migrate them.
Would appreciate discussion from @asthana86 , @eerhardt , @GalOshri , @glebuk , and @shauheen specifically on this topic. (To clarify all are welcome, just mentioning to make sure it gets flagged for them. 😄)
Activity
glebuk commentedon May 15, 2018
Sounds good. Let's start with the IDV and IDV type system docs at the very least. Later one we could add the rest.
[-]Migration of Code Documenation[/-][+]Migration of Code Documentation[/+]GalOshri commentedon May 16, 2018
This is great.
Additionally, it would be nice to include some additional information on how learners and transforms work in ML.NET (using the contribution tutorials). Although these can be migrated after the core IDV docs.
TomFinley commentedon May 17, 2018
Hi @GalOshri ... I'm sorry to say I won't make you happy on the tutorials. While I agree that they're practically quite useful in that it is one of the few things to treat in (excruciating) detail exactly how one goes about writing a component and how our infrastructure works from beginning to bitter end, that one will require considerably more work to adapt, because of course I am throughout the tutorial relying on existing idioms for invoking these, that are not true in the "new" ML.NET API. (And that are under considerable flux, so even if I were to phrase it in those terms, I don't have enormous confidence they will remain relevant.)
GalOshri commentedon May 18, 2018
Thanks @TomFinley! I think it's fine if they are not migrated immediately, but we should try to do that once there is a little less flux.
Migration of first `IDataView` docs (#173)
Migration of first `IDataView` docs (dotnet#173)
JRAlexander commentedon Aug 6, 2018
You could also migrate these to the dotnet/docs machinelearning repo. This would have several advantages, including rendering in Docs.microsoft.com, localization, and editing.
shmoradims commentedon May 21, 2019
Related to (possible duplicate of) #1831
codemzs commentedon Jun 30, 2019
closing since it is a duplicate of #1831