I'm proposing we consider removing the API guide's copy of the Satellite 6 API and instead rely entirely on the live documentation hosted on every instance of Satellite 6, eg: https://satellite6.usersys.redhat.com/apidoc/ By forcing the docs team to continuously make a copy with every release that needs to exactly reflect the above live documentation is asking for copy-paste errors and misrepresentation. Any bugs in the API docs should be fixed at the source in the source code itself instead of in the documentation. I'd propose we trim the API Guide down to *just*: Section I DELETE: Section II finish Section I with a pointer to the user's Satellite: """ To see the API your Satellite has available browse to http://satellite6.example.com/apidocs """
Since this issue was entered in Red Hat Bugzilla, the release flag has been set to ? to ensure that it is properly evaluated for this release.
(In reply to Mike McCune from comment #0) > I'm proposing we consider removing the API guide's copy of the Satellite 6 > API and instead rely entirely on the live documentation hosted on every > instance of Satellite 6, eg: > > https://satellite6.usersys.redhat.com/apidoc/ Ack. Commented same in https://bugzilla.redhat.com/show_bug.cgi?id=1132228 > > By forcing the docs team to continuously make a copy with every release that > needs to exactly reflect the above live documentation is asking for > copy-paste errors and misrepresentation. > > Any bugs in the API docs should be fixed at the source in the source code > itself instead of in the documentation. I've already had initial discussions with ggainey about this for Sat5 API and it seems straightforward from a docs perspective. I can devote a sprint or whatever to reviewing the API descriptions *from a docs/description perspective* and do edits and PR directly in github or wherever. > > I'd propose we trim the API Guide down to *just*: > > Section I If this includes some examples, yes. If not, I think it would be good to add a few. > > DELETE: Section II > > finish Section I with a pointer to the user's Satellite: > > """ > To see the API your Satellite has available browse to > http://satellite6.example.com/apidocs > """ ack to everything else.
Xixi, Please chime in for GSS opinion :). Cheers, Athene
(In reply to Athene Chan from comment #5) > Xixi, Please chime in for GSS opinion :). Cheers, > Athene From email thread "Re: [NEEDS ACTION] 1. Async release this Friday 2. API Docs", the biggest concerns I can see is a significant impact / major inconvenience for customers and support: a) Having access to the docs regardless of access to a Satellite (not everyone will have a Satellite handy at any moment) - this is true for both customers and support, both existing Satellite users and potential customers (who can immediately see what the APIs have to offer). b) Having the newest and greatest doc to refer to in a public location - customers may have different/older versions of Satellite but this helps to stay on the same page. For Satellite 5 for example, there're docs for 5.4, 5.5, 5.6 etc. and each set of docs are updated for that point release (with async erratas etc.). So IMHO the aim is to reduce docs team load without impacting customer experience - how big is the effort to maintain the API guide and how can we reduce that (perhaps improving the publishing process)? E.g., if the API examples are the time sink, then perhaps we trade that off into kbase instead of official docs. From latest on the thread: > On 9/30/14, Athene Elswyth Chan wrote: >> I think the question would be, when are the APIs updated? Most of the >> process of generating the API docs are scripted by Dan. The following >> are manual: 1. Branding 2. Revision History 3. Publishing (which due >> to the manul process atm takes up time) >> >> I think the time sink that will matter more in the future will be >> providing examples for the API. GSS, from time to time, asks for >> examples and looking for examples is harder for us because we either >> have to test it out ourselves or look for devs who can provide these >> examples. >> If this is the time sink, how about let's offload to/supplement with kbase instead of official docs. The current API docs already have some good basic examples, the rest can reside in a kbase or even public repo. The basic usage of API calls trumps any additional examples, IMHO. >> However, having said that, we are willing to maintain the guide and >> if customers find it an easier source to refer to APIs (especially >> for those who do not own Satellite). We can probably tack on a note >> on it to say that the APIs were generated on "X" date and may not >> have all the updated APIs? >> Thank you - it sounds like the remaining question is when/how often the API guide is updated (and BK's suggestion at bottom of this thread)... Mike? (more in-line) >> Cheers, Athene Chan >> [snip] >>>> >>> Mike.. can we extract the docs to a known location? That way we >>> have a generated "correct" set per releease, but not have to >>> include a documentation process? >>> >>> -- bk >>> Thanks all, -- Xixi Global Tech Lead, System Management SEG / GSS / CEE
*** Bug 1132228 has been marked as a duplicate of this bug. ***