Service documentation is confusing for target audience


#1

Whoever wrote the docs should go back and try and put him/herself in the shoes of someone just coming to Atom… Especially the last code block… it would be much nicer to provide a more thorough explanation of how to consume/use a service…


#2

Perhaps you have some constructive suggestions on what can be changed? Maybe some ways of rewording things to make it more clear? Or even specific examples of what you found confusing or unclear would be more helpful than, essentially, go back and try again.


#3

Sure thing, here we go…

It would probably be better to illustrate how the same service is produced and consumed. In the configs in the code blocks, rather than have “my-service” in the first example, and “another-service” in the second example, it would make more sense to illustrate offering and consuming the same service successfully.

In the last code block

{Disposable} = require 'atom'

module.exports =
activate: -> # ...

consumeAnotherServiceV1: (service) ->
  useService(adaptServiceFromLegacyAPI(service))
  new Disposable -> stopUsingService(service)

consumeAnotherServiceV2: (service) ->
  useService(service)
  new Disposable -> stopUsingService(service)

useService() looks like an api call as opposed to shorthand for “do something”

Also, it would be nice to provide some sort of description of how to debug problems. How can you tell what services have been successfully produced/consumed. I personally had an issue whereby I had the a package provide a service and another one consume said service, but something was going wrong. However, there didn’t seem to be any hint as to how to proceed with debugging. I am pretty sure that most newcomers to services will hit the same wall.