Never refer to the official documentation for help

  • (2 Pages)
  • +
  • 1
  • 2

22 Replies - 1491 Views - Last Post: 24 June 2017 - 09:18 AM

#1 bobsmith76  Icon User is offline

  • D.I.C Head

Reputation: 8
  • View blog
  • Posts: 61
  • Joined: 14-February 17

Never refer to the official documentation for help

Posted 06 June 2017 - 11:41 AM

As a rule whenever I try to figure out how to do something, I never refer to official documentation for help. I always go to one of these third party websites that try to help you out. To the designers of code it is just obvious how it works, so they rarely see need to explain things in simple terms. Or maybe they believe that lesser minds will take up the challenge of explaining it and decide to devote their time to more productive activities.

Does anyone else follow this rule?

Is This A Good Question/Topic? 0
  • +

Replies To: Never refer to the official documentation for help

#2 modi123_1  Icon User is offline

  • Suitor #2
  • member icon



Reputation: 13566
  • View blog
  • Posts: 54,125
  • Joined: 12-June 08

Re: Never refer to the official documentation for help

Posted 06 June 2017 - 11:51 AM

Quote

Does anyone else follow this rule?

Most definitely 'NO!'. Why get mired in third or fourth hand interpretation when you haven't gone to the horse's mouth first to see what's up?

So.. give it up. Who are you feeling angsty against for some perceived burn or slight? ;)
Was This Post Helpful? 0
  • +
  • -

#3 bobsmith76  Icon User is offline

  • D.I.C Head

Reputation: 8
  • View blog
  • Posts: 61
  • Joined: 14-February 17

Re: Never refer to the official documentation for help

Posted 06 June 2017 - 11:59 AM

I just rarely understand the official documentation, that's all. No angst felt.

As far as

Quote

Why get mired in third or fourth hand interpretation when you haven't gone to the horse's mouth first to see what's up?

I think I made that clear when I said:

To the designers of code it is just obvious how it works, so they rarely see need to explain things in simple terms.
Was This Post Helpful? 0
  • +
  • -

#4 modi123_1  Icon User is offline

  • Suitor #2
  • member icon



Reputation: 13566
  • View blog
  • Posts: 54,125
  • Joined: 12-June 08

Re: Never refer to the official documentation for help

Posted 06 June 2017 - 12:07 PM

I doubt I have found a decent team that doesn't have a good documentation to show basic functionality, explain methods, etc. Outside of a few bad apples who is scoffing at people for asking for help? Presuming said help isn't already in the documentation..

Ultimately I think it is a bad idea. The generalize that people who provide documentation and what not are too busy for questions is a little short sighted.. then again just turning to scream for help when examples exist/FAQ/tutorials is equally annoying.

So why not try the documentation, read for understanding, try a few things out, and see if there are examples/tutorials given as well. Typically folk want their stuff to be used and try and facilitate that. Some may not spoonfeed it as much as others, but the help is typically there.
Was This Post Helpful? 0
  • +
  • -

#5 bobsmith76  Icon User is offline

  • D.I.C Head

Reputation: 8
  • View blog
  • Posts: 61
  • Joined: 14-February 17

Re: Never refer to the official documentation for help

Posted 06 June 2017 - 12:49 PM

View Postmodi123_1, on 06 June 2017 - 12:07 PM, said:

So why not try the documentation, read for understanding, try a few things out,


From this sentence:

I just rarely understand the official documentation, that's all.

you can infer that I have already tried the official documentation.
Was This Post Helpful? 0
  • +
  • -

#6 modi123_1  Icon User is offline

  • Suitor #2
  • member icon



Reputation: 13566
  • View blog
  • Posts: 54,125
  • Joined: 12-June 08

Re: Never refer to the official documentation for help

Posted 06 June 2017 - 12:53 PM

Okely dokely.

Good luck with that.

Spoiler

Was This Post Helpful? 0
  • +
  • -

#7 NeoTifa  Icon User is offline

  • NeoTifa Codebreaker, the Scourge of Devtester
  • member icon





Reputation: 4099
  • View blog
  • Posts: 18,184
  • Joined: 24-September 08

Re: Never refer to the official documentation for help

Posted 06 June 2017 - 01:41 PM

What is "documentation"?
Was This Post Helpful? 1
  • +
  • -

#8 tlhIn`toq  Icon User is offline

  • Xamarin Cert. Dev.
  • member icon

Reputation: 6507
  • View blog
  • Posts: 14,379
  • Joined: 02-June 10

Re: Never refer to the official documentation for help

Posted 06 June 2017 - 03:23 PM

View Postbobsmith76, on 06 June 2017 - 12:41 PM, said:

Does anyone else follow this rule?


Nope
Was This Post Helpful? 1
  • +
  • -

#9 tlhIn`toq  Icon User is offline

  • Xamarin Cert. Dev.
  • member icon

Reputation: 6507
  • View blog
  • Posts: 14,379
  • Joined: 02-June 10

Re: Never refer to the official documentation for help

Posted 06 June 2017 - 03:46 PM

View Postbobsmith76, on 06 June 2017 - 01:49 PM, said:

I just rarely understand the official documentation, that's all.


That doesn't make the documentation bad.

You have to keep in mind that its not reasonable or possible to expect documenation on an advanced topic... say... "How to capture photos in a cross-platform mobile app"... to also include the simple basics such as... 'properties' or 'OOP'.

It is incumbent on the developer to cover topics starting with the basics and increasing in complexity. You can just jump in to the complex and thing you're going to 'pick up the simple stuff' as you go along.
Was This Post Helpful? 0
  • +
  • -

#10 Skydiver  Icon User is offline

  • Code herder
  • member icon

Reputation: 5928
  • View blog
  • Posts: 20,267
  • Joined: 05-May 12

Re: Never refer to the official documentation for help

Posted 06 June 2017 - 07:23 PM

I usually read the official documentation first, followed by reading the source code, and then turn to 3rd party articles, blogs, and books.
Was This Post Helpful? 0
  • +
  • -

#11 xclite  Icon User is offline

  • I wrote you an code
  • member icon


Reputation: 1253
  • View blog
  • Posts: 4,043
  • Joined: 12-May 09

Re: Never refer to the official documentation for help

Posted 07 June 2017 - 05:51 AM

Even if the documentation is wrong, at least it gives me some inkling as to the intent, which is usually half the battle.
Was This Post Helpful? 1
  • +
  • -

#12 andrewsw  Icon User is online

  • say what now
  • member icon

Reputation: 6410
  • View blog
  • Posts: 25,908
  • Joined: 12-December 12

Re: Never refer to the official documentation for help

Posted 07 June 2017 - 08:24 AM

The official documentation - the horses' mouth - typically has one or zero examples (depending, of course, on the language/resource), so although it is usually (and should be) the first point of contact, it is rarely the end of search/research. We have the internet, we don't have to wander down to the library to borrow a second book ;)
Was This Post Helpful? 0
  • +
  • -

#13 jon.kiparsky  Icon User is offline

  • Chinga la migra
  • member icon


Reputation: 10731
  • View blog
  • Posts: 18,359
  • Joined: 19-March 11

Re: Never refer to the official documentation for help

Posted 07 June 2017 - 08:28 AM

It's true that the first documentation generated is usually aimed at experienced developers, and is going to make a lot of assumptions about what the reader brings to the game. This is typically at the man page level - documenting what switches have what meanings, call syntax, and so forth. Basically, it tells you how to do stuff, but not much about what you can do and nothing about why you'd want to do it, and the "how" documentation assumes a lot of baseline knowledge. This is particularly true of open-source products, and of developer-focused tools.

Typically, this lack is filled in by developer blogs, conference talks, and by sites like stack overflow and DIC. People who fill in these gaps tend to either be the original core developers or they become evangelists and experts on the product. Look to these people for the third-party documentation (ie, O'Reilly and Pragmatic titles about the product)

As a product matures, you start to see more about the "what" and the "why", and the official documentation becomes more beginner-friendly. At the same time, if the product has enough user base, you get third-party documentation, and the beginner finds it a lot easier to use the thing.

I have long observed that one of the obvious assumptions about this process, which is that the step-2 fill-in is done by people who are already experts, is not generally correct. In fact, the way that people become experts is by answering questions. If you do the research to answer questions, and if you do the work to explain the results of that research clearly and succinctly, you develop a lot of knowledge. If you put together a half-hour talk for your local user group, you develop expertise on that topic. Over time, this makes you a known authority on the topics you've chosen to be curious about. The critical thing is, as a beginner finding yourself stymied by a particular question, you have a valuable resource, which is a particular curiosity that is certainly shared by others in your position. So, if you find that the documentation for some product P is not meeting your needs, it is very likely that you are the best person to answer that question, and that you will benefit greatly by taking on that challenge.
Was This Post Helpful? 1
  • +
  • -

#14 jjl  Icon User is offline

  • Engineer
  • member icon

Reputation: 1270
  • View blog
  • Posts: 4,997
  • Joined: 09-June 09

Re: Never refer to the official documentation for help

Posted 19 June 2017 - 02:07 PM

You do realize that if everyone followed that mentality, then nothing would get done. All you are doing is getting the spoonfed version from someone that read the real documentation.
Was This Post Helpful? 0
  • +
  • -

#15 jon.kiparsky  Icon User is offline

  • Chinga la migra
  • member icon


Reputation: 10731
  • View blog
  • Posts: 18,359
  • Joined: 19-March 11

Re: Never refer to the official documentation for help

Posted 19 June 2017 - 02:16 PM

Considering that every developer in the world starts with stack overflow when they have questions, I think that everyone is following this mentality, and things are getting done. In fact, many people think this is an improvement over the situation twenty years ago, when your options were basically to read whatever official documentation existed, read the source code, or hope that O'Reilly had published something about it.
Was This Post Helpful? 0
  • +
  • -

  • (2 Pages)
  • +
  • 1
  • 2