Why is GitHub used when you have a documentation site?

#1

Is there any reason why some resources are available on Git Hub and some are in the documentation section?

Is there any reason why resources that are required in the API calls are not available via API calls? (description lookups etc.) I assume if these resources are updated, there will be some announcement? otherwise how will users know if they have changed?

I find myself having to refer to specific forum posts in order to find documentation links to github, that are referenced nowhere on the documentation page!!

Is this the on going plan, or will the documentation be updated at any point?

Hywel

2 Likes
API Changes - how to know when they are made
#2

Could not agree more!

Frank Murphy, StatBooks Ltd

#3

The recent posts about SIC Codes, and other like them, reinforce the original point that Hywel made here ( and that I supported). It would be so much easier for ALL users but especially those new to the API, if all of the supplementary documentation was in once place and the right place here with the core documents instead of lurking on Github. A developing Index would be nice too!

#4

@frank

Thanks for the comments which provide valuable recommendations that we can feed into the development of the service and its associated documentation moving forward. At the time of the original post we added links from the core documentation to the enumeration files on GitHub so that it was available centrally, but maybe we need to make this clearer.

Thanks,

@mfairhurst

#5

Mark

The point that I am trying to get across is the one that Hywel made in the first place.

A Single Reference Point is needed for ALL documentation rather than some being available from the API front page modules. some supporting information then being on Github with access from the front end of the Companies House API and the remainder from links in Forum Posts. In my view, a “Document Library” link on the front page (https://developer.companieshouse.gov.uk/api/docs/) with all the support documents behind it would be ideal now and in the longer term as the resource grows. That also suggests that it would easier to do it soon and build on rather than do it later when the volumes are far larger.

I do not have a problem in (eventually) finding what I need but it does seem that others, especially new users, do and are taking up your time with questions that should not arise with an orderly SRP. I should stress that this is intended as a constructive suggestion rather than a criticism of what has been delivered to date.

Regards,

Frank Murphy, StatBooks Ltd

1 Like