Why are there no examples in the Xamarin API documentation?

ekline309ekline309 ✭✭USMember ✭✭

If you notice Microsoft MSDN has excellent examples for each API entry, yet Xamarin has none. What gives? Can you add this to your API documentation please.

Best Regards

Answers

  • HunumanHunuman ✭✭✭✭ GBMember ✭✭✭✭

    Hi @ekline309

    You can use the Xamarin.Forms Samples as a good alternative.

    Hope this helps,

    Tim

  • NMackayNMackay mod GBInsider, University mod

    It's a fair point.

    The API reference is next to useless as it's just describes the method etc.

    Unlike the .NET MSDN samples (which aren't usually real world), there are different implementations per platform but I'd agree that listing the API interfaces aren't that useful, it's lazy and F2 will give you the same information, it's not useful information when listed.

    Mono is evolving as is Forms though so stable documentation isn't going to happen soon, I agree that Microsoft needs to do much much more rather than just relying on bloggers.

  • N_BauaN_Baua ✭✭✭✭✭ INMember ✭✭✭✭✭

    Hi @ekline309 ,

    This is really a good point, The API updates also are not sometimes known as changes made, until the compiler notifies that something is deprecated and/or your code breaks.

    If GURUs like @NMackay :wink: think and suggest this as a good idea, I would love to propose a blog/web portal only dedicated to do thing Xamarin Forms way, moderated by 2-3 people from XF Community and mostly filled by user submissions/XF expert users.

    I would love to see this with such blog/web categorized as with posts: ....

    • Basic API access examples -- Say for instance, how to use Frames and create rounded label effect OR how to set WebView scroll height.
    • Advance API access examples -- Say for instance, how to read contacts OR how to record/save a sound.
    • KB Posts -- Posts which guides users with knowledge based articles, Say for instance, difference between Behaviors, Triggers and when to use what.
    • New features - News/Posts about newly proposed or introduced features by Xamarin Forms.
    • Code Snippets - For instance, Sample Codes- Hacks or Work-arounds implemented by XF community users.
    • OS Specific Codes - For instance - When there is no alternative but to use Custom Renderers etc
    • Third-Party Tools/Plug-ins/Code Snippets - Posts with Git Links and third party article/web URLs which will drive users who are looking for paid/free components.
    • Announcements/Events - Posts with offers, announcements, events and more.

    Guys, please forgive, if I've over stated, however I've been working on XF in early days (that was pain) and left in between, now again returned to the XF home ground, seeing lot of improvements, though I want the others to gain from us and not suffer like the hell we all did. So please suggest, if the above solution can be worked out with a WordPress or any other online blog or may be with some personally funded domain.

    Hoping to do best for XF community. :cookie::cookie::cookie::cookie::cookie:

    Regards,
    N Baua

  • ClintStLaurentClintStLaurent ✭✭✭✭✭ USUniversity ✭✭✭✭✭

    Documentation is awesome. It would be even better of 80% of rookies bothered to read it.
    I'm jaded and I admit it.

    But honestly, they come here and StackOverflow and DreamInCode asking how to set the text of a label, how to change the color of a button... and 1,000 other basic things that are already documented and they are just to lazy or have a horrible education/work ethic and can't be bothered with actual reading and learning. They ask, then copy/paste the code in the answer.

    So, from that perspective I would rather see the limited number of Xamarin employees working on FIXING THINGS than on writing documentation that won't be read. If there is something that actually NEEDS an explanation, then they need to do a better job of answer emails when questions are asked. maybe use those emails as a prioritization guide for what documentation needs to be written first.

  • N_BauaN_Baua ✭✭✭✭✭ INMember ✭✭✭✭✭

    Hi @ClintStLaurent,

    Thanks for your views, I agree on what you say that people do not bother to read the API and documentation and ask a silly basic questions, However in my opinion we should stop encouraging such questions, I do not see that happening soon. So what do we do now, do we stop answering the legit users who really are in need.

    For that reason, there should be some concrete platform which will help both the novice as well as experienced users.

    And yes Xamarin folks are Limited and doing their best, no doubt about it.
    Its rather the question, (apart from the main question on the thread) What we can do for the Xamarin community?

    I hope I am not being rude to you or anyone, I feel we can make difference, by doing something new. Who knows!

    Regards,
    N Baua

  • JohnHardmanJohnHardman mod GBUniversity mod
    edited July 2017

    @DavidOrtinau - tagging in case this is of interest :-)

    I'm a big fan of XML comments, parsed by tools such as doxygen to create documentation in HTML and other formats, as well as providing the information for Intellisense. That's where the basic API usage should be documented, as having it in the code means it's more likely to be updated when code changes are made. Of course, the resulting documentation is only as good as the XML comments, so they have to be given some thought to be useful, which can definitely be a battle with some developers.

    Beyond that, there should be samples of how to use every property, method etc of every class in the Xamarin.Forms APIs, using both C# and XAML. I continue to be astonished that the QA folk at Xamarin/Microsoft don't have this in place to be used as part of their own automated testing.

    The two bits above would be equivalent to the main stuff found in MSDN for other Microsoft APIs. If Xamarin insiders don't have time to do the above two bits, they should be hiring more people.

    Beyond that, "how to" guides for common requirements (such as building renderers) would definitely be useful. Having those come from Xamarin-insiders would be ideal, but they still seem too stretched. This is where non-Xamarin people can provide useful info in blogs, on the forums etc., although again, I think Xamarin should hire a couple of people whose job is to answer forum questions using their inside knowledge. I'm sure they will say that they provide support privately for paying business users, but I would question whether it is worth paying for - I've had some pretty abysmal responses, as well as non-responses.

    I do also agree with @ClintStLaurent regarding a number of questions on forums - my initial reaction when reading a question is often "Surely you could have Googled before asking that?" or "You're really asking us to write your code for you?". The latter is the reason I ask OPs to post their code for others to comment on, rather than just responding to them with a chunk of working code.

  • ClintStLaurentClintStLaurent ✭✭✭✭✭ USUniversity ✭✭✭✭✭

    @JohnHardman said:
    I do also agree with @ClintStLaurent regarding a number of questions on forums - my initial reaction when reading a question is often "Surely you could have Googled before asking that?" or "You're really asking us to write your code for you?". The latter is the reason I ask OPs to post their code for others to comment on, rather than just responding to them with a chunk of working code.

    I've stopped doing that, I'm sad to say. I'm tired of getting my request for proof of their efforts getting tagged as SPAM or ABUSE. Apparently not just handing over working code is abuse to these special snowflakes.

    I'm sorry to say I end up just deleting 80% of the notices when they show in my Outlook. I read the email summarizing the question and say the same thing John did - _No I'm not writing your question for you... If you can't put in 10 minutes of effort trying to learn from the thousands of tutorials out in the world, then why would I spend 30 minutes writing a good explanation? _ That leaves about 5 questions where the OP seems to actually be making an effort. I hope that maybe the 3-5 questions I can offer some help in are a different 3-5 than John has time for, and those are different than the 3-5 that Normal grabs. And so on.

    Its a simple matter of hours - there aren't enough of them. Rather than write the same thing over and over, I'd rather spend that time making one good, completed, illustrated example on my tutorial site - then I can put a link to that 15 times a day if I had to. Its not about driving traffic there: I could care less about traffic. Its just a more efficient use of the 4 hours a day I have for ALL of my personal time; which has to also include costuming, 3D printing, coding, time with the family, maybe a TV show if I'm lucky.

    @N_Baua I don't think you're being rude to anyone. Just to be clear. I think in concept what you're saying is wonderful. Everyone should document. It would be wonderful if there were more for people, rookies or power users. Yes it is genuinely needed.

    I think there is a lot of "something has to change" and "someone should come up with something" posted in various threads here - which we all agree on in principal - but its that last 5% of what exactly that 'something' that's the tricky part. Mostly I think its just the sheer grunt effort of doing the work - of writing the documentation. There's not much of a magic bullet for that. Its just a lot of man-hours. Maybe its a good place to bring in a thousand interns who will put in the hours just to put on their resumes.

  • ekline309ekline309 ✭✭ USMember ✭✭

    It's simply a matter of completeness in order to catch any and all edge cases Thank you John, I will look into doxygen, I was not familiar with this technique for generating documentation.

  • N_BauaN_Baua ✭✭✭✭✭ INMember ✭✭✭✭✭

    @ClintStLaurent

    Thanks, I can understand your point. and @JohnHardman has also given good marker here -- Googled before asking that?
    Really ditch those guys who want us to code for them. Yet still I'll be posting solutions if I feel genuinely someone has tried and not yet came over issue after real efforts.

    Great guys, I loved the way you open up :smiley:

    Regards,
    N Baua

  • NMackayNMackay mod GBInsider, University mod
    edited July 2017

    I found myself trying to answer a question about setting the navigation bar color earlier even though I've been working on a massive refactoring job to allow us to build multiple apps but share a lot of common code, I can't commit the time anymore, it would be good if the admins could filter the basic how do I but I think only a few MS folk are checking this place and maybe on their own time.

    It's a fantastic community though and there's tonnes of great people looking for assistance, I just wish some people would use google 1st, 75-80% of the time you'll find the answer there.....half the time on Stackoverflow, If you can't find it then post a question.

Sign In or Register to comment.