Xamarin Documentation on StackOverflow

AdamPAdamP AUUniversity ✭✭✭✭✭
edited July 2016 in General

I am intrigued by the new StackOverflow documentation. However I am not convinced on how this is all setup and hoping some discussion might help to sort things out.

Take for example Custom Renderers Topic Request for Xamarin Forms.

When you go to create the Topic you are presented with these things
1. Examples
2. Syntax
3. Parameters
4. Remarks

It says all good documentation starts with examples. But I am disagreeing on this point for this topic. For example look at the description added: Strategy for custom renderers, why what when how

There is no one example for a custom renderer and I don't even think it should start with that. I would initially start with a description and diagram on the concept of custom renderers.

Examples come next, but example for what? You can either do your own custom renderer or extend one of Xamarin Forms existing ones. In which case do we need a new topic for each one, expanding LabelRenderer for example, otherwise the list of examples will be completely overwhelming.

There doesn't seem to be anyway to tie this all together. However I may be looking at this documentation concept incorrectly and should we just be doing a documentation piece for LabelRenderer for example, without having the overview explaining the concepts first or bothering to link the others together?

Apologies, I am going to tag in a bunch of people here otherwise they won't see it and I know they will most likely have some good discussion points around this: @CraigDunn @PaulDiPietro @NMackay @GeraldVersluis @JohnHardman @KymPhillpotts @AlessandroCaliaro @ThomasBurkhart

Posts

  • GeraldVersluisGeraldVersluis NLUniversity ✭✭✭✭
    edited July 2016

    I agree on that it should start with some kind of an introduction. In my opinion documentation should be readable by a beginner as well as an expert, both looking for other things in a piece of text. These can actually best be clarified with example code, of course.

    But now it feels like, how you describe it, that it will just be a whole bunch of examples of snippets code without much background information. Like the 'regular' StackOverflow sometimes causes a bit too much of just copy and pasting code I believe this format in documentation will even cause more of this behaviour.
    It seems a bit odd because when asking and answering questions on StackOverflow it is encouraged to provide background information and the why, who and what and not just a copy and paste ready to go solution. So that the person asking the question will actually learn something. Again, the format in which this documentation is to be added seems to kind of defeat that purpose.

    I feel it should be more wiki style, or better yet: Xamarin Workbook style that you can provide a whole article with Markdown and (live) examples to guide someone through the concept of i.e. custom renderers.

  • JohnHardmanJohnHardman GBUniversity mod
    edited July 2016

    @AdamP @CraigDunn @PaulDiPietro @NMackay @GeraldVersluis @JohnHardman @KymPhillpotts @AlessandroCaliaro @ThomasBurkhart

    Just my initial thoughts…

    My main question is about how this integrates with other forms of documentation.

    For example, let’s say a user wanted to learn about how to use a ListView to get variable height rows that can expand or contract dynamically based on their content (this is a forum topic that keeps arising).

    Using StackOverflow documentation, we can create documentation and include example code. That’s fine. But the documentation that we create is reliant on ListView behaving the way that we expect, even in future versions of Xamarin.Forms . If the ListView itself is thoroughly documented by somebody who knows the strategy/roadmap for ListView then the samples we create can be based on a solid understanding of the ListView foundation. However, if ListView itself is either not documented or documented by volunteers not in-the-loop on the future XF roadmap, then everything we submit about expanders/contractors could be ok now, but wrong when XF is next updated. The foundations need to be documented by people in-the-loop before volunteers can build on top of it.

    Further, so that intellisense works in a useful way, the most basic foundations need to be XML comments in the source code, not on StackOverflow. Given that, it might be useful to have links from the XML comments to the repository of related subjects on StackOverflow. That probably means have a master index page (with a URL that doesn't change) on StackOverflow for each headline topic (e.g. ListView), that behaves as an index to the separate pages showing the items added by volunteers.

    To cope with users with different native languages, it would be useful to have the same examples wrapped in text for different languages, so although one person might contribute the code and text in one language, another volunteer might translate the text but use the same code (not as a copy/paste, but the same URL for the code) to create a page in a different language.

    The other consideration that springs to mind is about the license relating to stuff on StackOverflow. There was a fuss recently when the license changed, although I didn’t personally see an issue with that change. What happens if the license changes again, in a way that makes corporates ban using code from StackOverflow (I have worked for clients who are very strict about which licenses they will and won't allow to be used)? If StackOverflow becomes the main repository for documentation and samples, a change to the license could be very awkward for developers in the corporate world. (BTW - I did ask about this regarding the Xamarin.Forums months ago, but never got an answer).

  • NMackayNMackay GBInsider, University mod
    edited July 2016

    I'm not a huge fan of this to be quite honest, I've found stackoverflow useful for searching edge usage cases of .NET/API's etc and getting a real world example of an MSDN topic as the samples there seem to have been written the designer or someone with intimate knowledge of the library.

    As a support channel I'm not convinced at all with stackoverflow, I've had this argument with our CSM 20 minutes ago.

    I wish they'd focus on getting the documentation improved on Xamarin.com, get Xamarin workbooks out to users as it will be far more useful for learning the product than this will be.

    Unless Microsoft plan on buying stackoverflow as well, they need to focus on the core Xamarin documentation and keep support as it's far far to complex a product and still relatively new to just allow it to be supported by msdn support (which is poor from our enterprise experience) and stackoverflow.

    I fully agree with the comments above, sorry for going a little of topic although support and this are linked.

  • ThomasBurkhartThomasBurkhart DEMember ✭✭✭✭

    I'm also made some thoughts about this:

    1. Does it make sense to publish ower own dev blogs or contribute to SO?
    2. MS just lauched https://docs.microsoft.com/de-de/ as a replacement for MSDN which grew into something almost unusable in the meantime. I have no clue what MS strategy is in this.

    Concerning your thoughts:

    • A Wikipedia style documentation center would be the better approach but:
    • My gut feeling is that most people will use SO docs like they do normal SO meaning by using Google and not asking questions. So it could make sense to add just samples there that can be easily found by google. E.g. just put all CustomRenderers that you have done so far in there so that anybody can find them at best together with a link to the containing github repo.
    • I don't see a real problem concenring licences because their is only limited copyright on shore code snippets at least in Germany, this may differ in other parts of the world.
    • I too see a big problem with samples that they are pretty fast outdated when new API versions are released. Who will keep them up to date?

    As a support channel I also don't see SO as the ideal channel. I'm more and more a fan of Slack because most often it takes only to point people asking a question in the right direction providing a link or just some knowledge you have instantly accessible in your mind. Somehow a developer chat is like a global dev awareness.

  • GeraldVersluisGeraldVersluis NLUniversity ✭✭✭✭

    I did an attempt by translating the DependencyService TTS Xamarin documentation to SO.

    Just to see if I could put in a documentation page what I would like to. And as I though on beforehand, I can not.
    Like stated before the format in which they want to put this just doesn't feel intuitive. I feel I have to dive right into technical stuff and I can imagine that a beginning developer is thrown off track right away, or worse; is going to copy/paste code right off the bat while having no idea what he or she is doing. I then foresee those people coming back to SO asking questions about why it is not working in their app after just copying and pasting it.

    Anyways, let me know what you think about the bit I did here.

  • AdamPAdamP AUUniversity ✭✭✭✭✭

    The documentation is good but I think it needs more of an intro.

    E.g. (a simplified version)

    1. Dependency Service is a way to call native code from a shared code based such as a PCL. Maybe a generic diagram after this.

    2. Xamarin Forms has a built in feature called DependencyService. To use it.
      a. Create an interface, this is an abstraction that your shared code will see.
      b. Create your native implementation on each platform and implement the interface.
      c. Use the Assembly attribute (show example) to register your native implementation with the dependency service.
      d. Here is how you call it from your shared code.

    3. Then walkthrough the TextToSpeech example.

    And this is probably what I mean when it wants you to jump in with examples straight away. Its great if the documentation was just for LabelRenderer as anyone going there would likely just want to delve right into an example as they know what Custom Renderers were. But what about people who don't know about Custom Renderers. To me it seems like Stack Overflow Documentation is excluding this type of documentation. Maybe I am not meant to do documentation as described above but just straight up technical documentation straight away as needed. Intro stuff is left elsewhere?

Sign In or Register to comment.