Closed skrabbe001 closed 2 years ago
roji
commented
2 years ago We generally include examples in our conceptual docs, and not in API docs; we point to the relevant conceptual section from the API docs. In any case, you're referring to (non-Core) EF6 docs, which are no longer under active development.
ajcvickers
commented
2 years ago This issue has been closed because EF6 is no longer being actively developed. We are instead focusing on stability of the codebase, which means we will only make changes to address security issues. See the repo README for more information.
skrabbe001
commented
2 years ago This is not true. I have been a developer for 30+ years, and I did not write it to debate you. Not only do you not provide adequate examples, for a lot of stuff you don’t even have API doc in the first place, for example .net core annotations. They are documented for EF6 but not for EF Core. Lately I have had to resort to checking the bug reports to the manual pages, to even find out what a method does or what an error message means.
I did not write you to debate if your culture is becoming worse with regards to writing documentation, examples and samples. I could write for months about the bugs and inconsistencies in EF Core, but I am busy trying to identify the bugs and inconsistencies in Azure (GUI, CLI, Docs, Samples, etc).
I wrote to inform you, that based on 30+ years of experience, developing on embedded devices, ZX80, Amiga, OS390, various Unix Systems, various Linux Systems, DOS, various Windows versions, iphone and android and more, that my impression of your documentation, samples and guides, is that you just don’t care. I referred you to check out ANY standard Unix manual page, to learn how documentation is done.
Now, you can ignore this, which I assume you will, or you can take action. But arguing with me is not going to change the facts.
Regards, Stefan
roji
commented
2 years ago @skrabbe001 I'm assuming you meant to comment on a different issue (possibly #3599).
We have our concept of how we write documentation, and how conceptual and API documentation stand in relation to each other; as written elsewhere, we prefer to link from the API documentation to the relevant conceptual docs, which themselves contain code samples and link to the appropriate sample source file.
Now, we care very much about our documentation and invest lots of time in it, every release. The results may differ in various ways from Unix manual pages - which in itself isn't necessarily a problem; it's OK for different documentation collections to approach things differently. More importantly, we've generally received lots of positive feedback about them from our users.
Of course, this isn't to say that we can't improve the documentation further. If you're interested in helping us do that, then what we need are concrete instances where our documentation is lacking or inaccurate; general comments about our docs being poor don't help us, as they doesn't identify where you encountered a specific issue we could fix. In your comment above, that ".net core annotations are documented for EF6 but not for EF Core", there's no indication of what annotations you're referring to; I'd be happy to hear more detail, so that we could go and make it better.
skrabbe001
commented
2 years ago I am not writing what I write below to insult you – but to show my frustration.
I am writing this, to give you an impression of how the Microsoft eco system looks, from a developer that has 30+ years of experience, 35+ languages, various frameworks and I have developed for both OS390, embedded systems, various unix’s, linux’s, windows, macs and iphone and android. I have worked as a system developer, backend developer, front end developer, office developer, you name it, I have done it.
Here we go.
Lets take a simple example, DefaultValueSql:
It does not refer to any “conceptual documentation” nor does it have an example.
The reason I keep referring to the unix documentation, is because Microsoft in general, does not seem to follow any guidelines at all, there seem to be no company policy, except that “who cares”, for how to write documentation for developers, tutorials, samples, etc.
If you search for EF core annotations, you find this link:
https://docs.microsoft.com/en-us/ef/core/modeling/entity-properties
It does not contain all the annotations, they are spread across multiple pages …… so what do I do if I do not know the name of the annotation or the category in advance?
I am currently writing software using the EF Core and .Net and C# and Azure (which frankly feels like getting spat in the face: CLI, GUI, Samples, Docs and tutorials) etc etc. I have minus 10 hours per day to work on fixing the official Microsoft products (it’s not my company) or web pages or samples or tutorials, etc. I am not a student that can spend my free time on improving the products of a private company. I could have written what I have currently written in 18 months, from scratch in C on a UNIX box in less than a month, without using any Microsoft sites, frameworks, or services, and it would be portable between Arm/x86 and between some UNIX’s windows and mac, and the setup and tear down of a box, would be scripted already.
===> most of my time is spend working around bugs, searching for examples, documentation, source code, wondering why the CLI doesn’t do what the GUI does, and vice versa, etc - and I have had ZERO luck with reporting specific issues. They close the issues without fixing them.
Some of the documentation is so bad, that I have to check the bug reports for the documentation, to find out what they should have written in the documentation. Many samples doesn’t compile, and you can see that the CI/CD pipline for them (on github where they are stored fials), etc. I find it so incompetent, that they release products for production, that are this crappy, and this is why I have begun being non-specific, because it is a problem with the Microsoft culture, and not just individual pages.
Sorry for the rant, but if I stay silent, nothing happens. Nothing changed for any of the “correct” specific issues I raised so far.
Sincerely, Stefan
roji
commented
2 years ago I'm sorry you have a bad experience with Microsoft documentation. I cannot answer for Azure or other Microsoft technologies - each team is focused on their products, and also has its own culture and approach to its product and documentation. Microsoft really isn't a single company with one culture, where we're told from above how to write (or not to write) our documentation.
More concretely about your points...
Lets take a simple example, DefaultValueSql:
Your link refers to API documentation for EF Core 2.2, which is an old and unsupported version. We have not been updating the docs for that in a very long time.
If you look at API docs for the corresponding user-facing API in the EF Core 6.0 documentation - HasDefaultValueSql-system-string)) - you'll see a link to the specific conceptual doc section covering that concept.
Also, the string annotation you were looking at (RelationalPropertyAnnotations.DefaultValueSql) isn't a user-facing API. In EF you typically use the fluent API method calls (such as the HasDefaultValueSql() method I linked to above) to configure your model; the string annotations are more of an implementation detail, but they still need to be publicly documented since they're sometimes referenced by other EF Core providers. EF is in the tricky situation of having both user-facing public APIs and provider-facing public APIs, and separating the API documentation for the two isn't easy to do.
More generally, I really recommend first getting some familiarity with EF via the conceptual docs; these contain introductory code samples and provide the basic concepts. The API documentation can then be used to explore the API and see specific parameters/return types in method signatures, but I wouldn't recommend it as a way of learning the product from scratch.
If you search for EF core annotations, you find this link:
https://docs.microsoft.com/en-us/ef/core/modeling/entity-properties
It does not contain all the annotations, they are spread across multiple pages …… so what do I do if I do not know the name of the annotation or the category in advance?
From our long experience in writing EF docs and helping users, we believe in documentation structured based on specific actions users want to do; for example, they want to configure a default SQL for some column, or define an index on some table. Our conceptual docs are structured exactly in this way, and the entity properties page lists the configuration (or "annotations", if you will) that one can perform on properties/columns. We have not seen users looking for "a list of all annotations", and I'm not sure why they'd do that.
In summary, I understand that the experience with our documentation can sometimes be frustrating. I can only urge you to point out concrete failings where you see them (as you've done above), and we'll respond and address them if necessary. General observations about the documentation or the culture unfortunately aren't very actionable, and won't help us improve the documentation in any specific way.
skrabbe001
commented
2 years ago As you can see by the example, that I did quickly while writing the mail, finding the right documentation in the first place is a time-consuming task. The documentation found was the top links found with google.
And as you say yourself, the documentation for a simple api call, is spread over many pages!!
How does a user navigate to the information he is searching for? Suppose he is looking for “annotations”, on this page:
https://docs.microsoft.com/en-us/ef/core/
Ie. suppose he is coming from EF6 and is looking for the EF Core page corresponding to the EF6 documentation:
https://docs.microsoft.com/en-us/ef/ef6/modeling/code-first/data-annotations
Also notice that the EF6 page just mentions a few of them. So, the documentation/manual pages are, regardless of the EF version, in my opinion designed to … be less than optimal. And I have the same impression of the tutorials and samples.
The only time I’ve encountered the same problems was when working with mainframes and the accompanying applications. It was a mess.
Even if I download the PDF for the pages I link above, searching it is a nightmare, because it contains both EF6 and EF Core documentation, an PDF is for printing, not reading in browser. HTML is, but there is not complete HTML page. I can go on and on.
My point is, that if I have these problems, then others have them too. I know my protocols, so I do not need a framework, but the developers I work with do. But what use is a framework, if it’s more time consuming and ambiguous and lacking than the RFC’s?
The documentation is like if I develop software without testing if the compiled binary works, or worse. No user tests. And if feedback is given, it’s “correct them yourself”, “we don’t have standards or guideles”, etc.
Also, that a company does not impose any guidelines at all on the divisions it has chopped itself into is …. Imagine calling me for help, and my excuse is that we don’t coordinate what we do? That we don’t have any standards? That he should write the documentation himself? Patch the source himself?
So again, I implore everybody that works with EF (and other Microsoft products) to be inspired by 30 year old Unix manual pages, like https://www.man7.org/linux/man-pages/man7/unix.7.html. Or sites like the cppreference.com, cplusplus.com, etc.
And I can’t mention enough, that raising issues on git-hub does not work. They are closed without solving the issues.
For example, when you install nodejs with visual studio, can you use and upgrade the nodejs installed by the visual studio installer? Or must you install it twice? Raise an issue with visual studio. Issuse closed, no changes to the manual pages. No one on stackoerflow knows.
Raising issues with azure = always closed OR closed and they write they will put it in their backlog … so they have a closed issue that isn’t fixed, which means other developers can waste time on it too, unless they waste even more time looking through closed issues.
Etc, etc, etc, etc, etc, etc.
Sincerely, Stefan
roji
commented
2 years ago @skrabbe001 as I wrote before, there's nothing I can say or do about Azure or NodeJS support in Visual Studio. You'll have to raise those problems with their owners.
How does a user navigate to the information he is searching for? Suppose he is looking for “annotations”
That has not been our experience. Users usually search for what they want to do, e.g. "create an index with EF Core", and not for an abstract concept such as "annotations". In any case, if, as you wrote above, a Google search led you to our entity properties page, then that indeed lists all the "annotations" for properties, which explains how you configure each aspect of a property with both text and code samples. This honestly seems like a good general outcome to me; if you're looking for other, non-property annotations, those can be found in the pages right next to the "entity properties" one, in the table of contents.
I'd like to help and improve things, but at this point I'm not seeing anything above beyond "your documentation is bad", which simply isn't actionable. If documentation for an anotation is missing or inaccurate, or you find anything concretely improvable in the EF docs, please let us know and we'll correct that.
skrabbe001
commented
2 years ago You wrote I should search for EF Properties, and not Annotations. Properties are not Annotations; an EF property is a member of a class. Annotations are C# Attributes that can also decorate a class.
I think the reason you don’t get more of these mails/bug reports experienced developers, is because they know it’s pointless.
skrabbe001
commented
2 years ago as I wrote before, there's nothing I can say or do about Azure or NodeJS support in Visual Studio. You'll have to raise those problems with their owners.
It was an example, to illustrate what I am talking about, not a request for you to help me with. I have not raised EF issues yet, because I assumed it was a waste of time.
roji
commented
2 years ago Our entity properties page lists the annotations that one can use on properties. As I wrote above, right next to that page is the entity types page with annotations one can use on classes. If your argument here is that we need to put them in one page, well, we'll have to agree to disagree.
I think the reason you don’t get more of these mails/bug reports experienced developers, is because they know it’s pointless.
You're entitled to your opinion; we get lots of issues about concrete problems in our docs, which we then fix. Maybe we don't get more because people are satisfied; our general observations and surveys indicate that this is the case.
skrabbe001
commented
2 years ago So here are some specific examples, as it doesn’t work to describe the problem that is present in all the pages:
It contains no description for if the expression should be a C# type or an SQl type, for example should empty string be “” or “’’”, etc. And the page doesn’t even link to other pages.
It contains no information of if the default is true or false. And the page doesn’t even link to other pages. This wastes time, and when all the manual pages are like this, it wastes tons of time.
And none of them contains an example, links to pages that links to it, links to examples that use it, known bugs, or the like.
I have contacted Microsoft multiple times over many years, and each time my colleagues laugh at me before I do it and say “don’t waste your time”. This has caused me to lose patience AND I have learned that politeness = nothing, a little irony = didn’t work either, sarcasm = nope, being pissed = not at all. But at least I know that I informed you, and we can laugh and joke about it, when I meet with my old student bodies and colleges.
I am just not like my friends and colleagues, I always try to see, if your culture has improved, which it did from 1995 to 2000, before it started to degenerate again. So if Microsoft EF Core want inspiration to improve, they can also look at Microsoft documentation from that period, as well as std Unix, C or C++ documentation.
Sincerely, Stefan
roji
commented
2 years ago It contains no description for if the expression should be a C# type or an SQl type, for example should empty string be “” or “’’”, etc.
These docs literally say "Gets or sets a SQL expression used as the default value for this column"...
But more importantly, that page is a link to the old EF 6 docs. As written above, we no longer maintain these. I already linked to the equivalent API doc page for EF Core - this one-system-string)), which both explicitly states that the parameter is a SQL string, and links to the conceptual docs.
At this point at seems like the conversation is going in circles... You seem to be generally frustrated with Microsoft documentation, and I'm sorry that this is the case - but the above comments simply aren't helping us improve.
skrabbe001
commented
2 years ago You're entitled to your opinion
The opinion that it should be easy to find what you are looking for.
But my main issue is still, the structure of manual pages for classes, individual methods, etc (synopsis, description, details, example, see also, known bugs)
skrabbe001
commented
2 years ago I didn’t just write, the documentation is bad. I wrote specifics, and provided examples of how you can write documentation. The examples I provided shows that you can improve documentation by:
Always provide a synopsis. Always provide a detailed description. Always include an example on the page itself. Always include a see also section on the page itself. Always include a known bugs section on the page itself. Make is possible to view the entire manual pages on a single HTML page. Always test what pages show up if you search on google / bing / etc – was the pages tagged correctly? How do we rank them better?
If these are not specific, I don’t know what is. I assumed that you knew what a unix manual page is, how it is constructed and I assumed that my search showed you that it is not trivial to find the pages you are looking for.
A guide is not a manual page. A sample is not a manual page. A beginners guide on how to create an EF model, is not a manual page.
If a user wants to lean about annotations he should search for properties? If a user wants to see the available EF Core annotations, he should look through many pages, and still not know if they are complete? If the product is in two versions, the documentation should follow the same structure. If you create a guide, make sure the source code in the guide and the source for it on github are identical. When we create a github sample/tutorial, makes sure it complies. Etc.
If you don’t want to address this, fine. If you want to not forward my concerns to anyone in the organization, fine – that is exactly what I am saying: Feedback is ignored.
skrabbe001
commented
2 years ago Is suggesting that you write manual pages like UNIX manual pages going in circles? I get it, you don’t want to write documentation for people that want to be productive. And don’t worry, you wont hear from me again – this is a farce.
skrabbe001
commented
2 years ago Users usually search for what they want to do, e.g.
So they don’t search for how a function works? Nice.
roji
commented
2 years ago @skrabbe001 I don't think there's anything new here, beyond what was already posted back in August. You're clearly frustrated about our docs, and I'm sorry about that; but I can only recommend not insulting maintainers (e.g. by calling their hard work "a farce") just because they don't agree with your point of view.
skrabbe001
commented
2 years ago We hired a new guy fresh out of university last month. While reading he EF Core Filter documentation, he said “it looks like it’s written by a 12 year old”.
I and my collegues waste MORE time figuring out how to use the Microsoft stack, then if we wrote it ourselves from scratch in C.
skrabbe001
commented
2 years ago And I know it doesn’t help telling you my opintion, or referring you to examples of how real documentation is written for programmers to programmers, re. unix documentation.
But the political correctness is irrelevant. This is not about feelings, this is about tremendous loss of productivity because the documentation, samples, tutorials and references are lacking. And it’s not ok, and I wont get ANYWHERE with politeness either (speaking from almost 40 years experience).a
From: Shay Rojansky @.> Sent: Tuesday, October 11, 2022 7:17 PM To: dotnet/EntityFramework.Docs @.> Cc: Stefan Krabbe @.>; Mention @.> Subject: Re: [dotnet/EntityFramework.Docs] The doc is missing an example (Issue #3897)
@skrabbe001https://eur04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fskrabbe001&data=05%7C01%7Csk%40gowiser.com%7C247dc3ce50a244ca5eed08daabac6a29%7Cbeaba489f54e4499b405d77a8d5532f8%7C0%7C0%7C638011054268069357%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=SDltCnAgmt1hiKRYv08CkUwBn%2BMVS0orDsUolqDtcRw%3D&reserved=0 I don't think there's anything new here, beyond what was already posted back in August. You're clearly frustrated about our docs, and I'm sorry about that; but I can only recommend not insulting maintainers (e.g. by calling their hard work "a farce") just because they don't agree with your point of view.
— Reply to this email directly, view it on GitHubhttps://eur04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fdotnet%2FEntityFramework.Docs%2Fissues%2F3897%23issuecomment-1275020969&data=05%7C01%7Csk%40gowiser.com%7C247dc3ce50a244ca5eed08daabac6a29%7Cbeaba489f54e4499b405d77a8d5532f8%7C0%7C0%7C638011054268069357%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=kpR9ihHa3Co0eOsXdnYXCS0agVjvVQrk2WfaqMtLCzI%3D&reserved=0, or unsubscribehttps://eur04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FASL4BKFP7YGKNAUAX27JMOTWCWOI5ANCNFSM5ZB2YURA&data=05%7C01%7Csk%40gowiser.com%7C247dc3ce50a244ca5eed08daabac6a29%7Cbeaba489f54e4499b405d77a8d5532f8%7C0%7C0%7C638011054268069357%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=HVOZTtqW%2B71AFv%2FABZR28Ixuq6IsDF3iPgvRcN9HWy4%3D&reserved=0. You are receiving this because you were mentioned.Message ID: @.**@.>>
This page, and a lot of other pages, is missing an example section. As it is now, it is unusable. If you want to see how to create documentation for developers, then check out the unix manual pages.
Document Details
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.