TECHZEN Zenoss User Community ARCHIVE  
FORUMS / ZenPacks, JSON API, and Integrations / DISCUSSION

Intro + New Developer Docs

Subject: Intro + New Developer Docs
Author: Adam McCurdy
Posted: 2019-04-03 15:37

Hey everyone,

For those of you who don't know me, I'm Adam McCurdy and I run the training program at Zenoss and have recently taken over responsibility for all product documentation. I've also been tasked with enabling and growing our community. I've been with Zenoss for over 7 years now and have served in various roles. I've met a handful of you in person, and look forward to interacting with you more as time goes on.

I just wanted to drop a note about some of the work we've been doing on developer docs -- a long-standing request from the Zenoss user-base. This post is the official soft-launch of the new Zenoss Developer Documentation site. There are still some issues with the content that need to be worked out before it's made more widely available, but I wanted to solicit feedback from our community sooner than later. Let me know what you'd like to see more of, less of, and if you find any issues with any of the technical content. Any feedback would definitely be appreciated.

This is the kind of thing you can expect to see more of going forward; we intend to invest more in technical discussions regarding development, integration, and some of the other more complex value-add features of Zenoss Core/Community Edition, Zenoss Resource Manager, and Zenoss Cloud.

Thanks for your time!

------------------------------
Adam McCurdy
Manager, Customer Enablement
Zenoss
------------------------------

Subject: RE: Intro + New Developer Docs
Author: Jane Curry
Posted: 2019-04-04 10:40

Good to meet you, Adam - many thanks!

Had a quick look at your link and the ZenPack SDK section looks like the stuff that used to be available at http://www.zenoss.com/community/docs/zenoss-api-docs/2.1/  but that now redirects to zenoss.com.  Looks like https://zenpack-sdk.zenoss.com/en/latest/   still works though.

I also have a bookmatrk for https://zenpackers.readthedocs.io/en/latest/   but that now gives "Permission denied" - there was some really good stuff under there :(

https://www.zenoss.com/services-support/documentation-options    from the forum main page -> Documentation, still has no link for Core documentation :(

Is this an ongoing re-org of documentation in general?

Cheers,
Jane

------------------------------
Jane Curry
Skills 1st United Kingdom
jane.curry@skills-1st.co.uk
------------------------------

Subject: RE: Intro + New Developer Docs
Author: Laurent Hemeryck
Posted: 2019-04-04 10:55

As Jane mentioned, it's sad that the ZenPackers documentation has been restricted. There was indeed a lot of useful information there.
Subject: RE: Intro + New Developer Docs
Author: Adam McCurdy
Posted: 2019-04-04 11:41

Hey Jane,

The SDK stuff in the new developer docs site is essentially what was in the old zenpack docs (https://zenpack-sdk.zenoss.com) site - the content authored by Chet.

I'm working on tracking down who owns the content @ https://zenpackers.readthedocs.io/en/latest/ to see what's there and why it got closed off.

The docs.zenoss.com page not mentioning Core is something that I'd raised with our website team but lost track of; thanks for the reminder. I sent them another ping on it and hopefully it'll get updated soon.
​
To answer your final question: yes - this is part of an overall re-org of documentation. Organizationally, documentation now sits under our "customer success" umbrella rather than our Engineering team, which puts the documentation closer to our user-base (a very good thing, in my opinion).

------------------------------
Adam McCurdy
Manager, Customer Enablement
Zenoss
------------------------------

Subject: RE: Intro + New Developer Docs
Author: Jay Stanley
Posted: 2019-04-04 10:50

I am very happy to hear you are being involved in the community, between you and Zack, I have high hopes.

As for the documentation. Off the top of my head..

Suggestions:
* Please change PostMan to Postman. :)
* If I send you my sample Postman collection, would you add it?
* Is there a chance of community edits or edit submissions?
* Would love to see a "This router is used for ..." on the routers page, instead of having to shift through all the methods.
* Would love to see a "Best Practices" section
* Tips/Tricks/Helpers section

------------------------------
jstanley
------------------------------

Subject: RE: Intro + New Developer Docs
Author: Jane Curry
Posted: 2019-04-04 11:00

Adding to Jay's thoughts...

An expanded Problem Determination section would be great.

Cheers,
Jane

------------------------------
Jane Curry
Skills 1st United Kingdom
jane.curry@skills-1st.co.uk
------------------------------
Subject: RE: Intro + New Developer Docs
Author: Adam McCurdy
Posted: 2019-04-04 11:50

Hey Jay,

I'll just go down your list and respond one-by-one:

I fixed the PostMman issue just for you.
Michael D (one of our SEs who I suspect you know) asked me the same thing; I'm a bit concerned about the security aspect of it, since those collections can contain sensitive information.
Community edits are unlikely for a number of reasons, but I'm open to take submissions.
Are you talking about on the router reference page where I basically did a lite-recreation of the epydoc format? Would you like an overview of what each router does there? Or would you want to see something like a master list with all of them explained in a table?
Best Practices is definitely something I'm interested in putting together.
I'd like to think of the documentation itself as a tips/tricks/helpers section, but if you have specific examples of the kind of tips/tricks you're looking for, I'm sure we can find something to do to help.

------------------------------
Adam McCurdy
Manager, Customer Enablement
Zenoss
------------------------------

Subject: RE: Intro + New Developer Docs
Author: Jay Stanley
Posted: 2019-04-04 13:36

Thanks Adam, my OCD loves you. :)

Re: Postman Collection) I have a scrubbed version of my collections that I was handing out and I have it as part of my ZenossDevHelper repo (currently private). Ill provide you something and you can look it over. I think it would be very useful for others.

Re: Router Info) Yeah, like on a page with a table or on the list you have so far. So, when looking them over you will have a good idea when looking for something without having to drill down.

Re: Best Practices) Yeah, like have sections. One of them could be Transforms ;)

Re: Tips/Tricks) Yeah, but I am thinking of having them broken out more.  I will write up a few examples, and you can let me know what you think

------------------------------
jstanley
------------------------------

Subject: RE: Intro + New Developer Docs
Author: Laurent Hemeryck
Posted: 2019-04-04 10:59

It would be easier to provide the feedback directly from this new website instead of the current discussion.

Subject: RE: Intro + New Developer Docs
Author: Adam McCurdy
Posted: 2019-04-04 11:52

That would be ideal, but it's not something that we can easily/readily accomplish.

------------------------------
Adam McCurdy
Manager, Customer Enablement
Zenoss
------------------------------

Subject: RE: Intro + New Developer Docs
Author: Jane Curry
Posted: 2019-04-04 11:10

Hi Adam,

I am assuming you know of the ZenPack Deveopers' Guide that I wrote 2.5 years back?  It was developed under Creative Commons Share Alike and you are very welcome to incorporate anything useful that you find there.

https://github.com/ZenossDevGuide/DevGuide

Cheers,
Jane

------------------------------
Jane Curry
Skills 1st United Kingdom
jane.curry@skills-1st.co.uk
------------------------------

Subject: RE: Intro + New Developer Docs
Author: Adam McCurdy
Posted: 2019-04-04 11:54

I actually remember seeing you lugging around a physical copy of that a few years ago at GalaxZ. We met briefly, but I'm sure you met a ton of people over those few days so I wouldn't expect you to remember.

I'll definitely take a look and see what we can use to augment our ZenPack docs when I have a chance. Thank you so much for all the effort you put in on that. I know it's been an asset to a lot of people.

------------------------------
Adam McCurdy
Manager, Customer Enablement
Zenoss
------------------------------

Subject: RE: Intro + New Developer Docs
Author: Laurent Hemeryck
Posted: 2019-04-05 04:46

Does this mean that the ZenPackLib documentation site (https://zenpack-sdk.zenoss.com/en/latest/) will also disappear ? 
I think that this web site has a big advantage because you can edit it through a pull request in GitHub. 
With the new web site, I don't see a way that the community could easily help and contribute.

Subject: RE: Intro + New Developer Docs
Author: Adam McCurdy
Posted: 2019-04-05 16:48

That site will indeed be decommissioned and we'll set up a redirect to the new site. While users could potentially edit docs through a pull request, I looked at the repo and can't find an instance of that ever happening in practice. You're welcome to make suggestions or contribute by working with me (and my team as we continue to invest resources) through the community.

------------------------------
Adam McCurdy
Manager, Customer Enablement
Zenoss
------------------------------

Subject: RE: Intro + New Developer Docs
Author: Jay Stanley
Posted: 2019-04-08 08:19

@Adam, sent over my postman collection.

A "Test your ZenPack" section would be nice as well.
Some topics could be:
  • Testing Installation
    • Verify install, verify removal (verify all objects that should be removed were)
    • When should you modify install() remove()
    • Best practices when modifying install() and remove()
    • Migration scripts
  • Negative Testing - How does your ZenPack components handle failures (wrong url, port, non-admin user, bad permissions, zProps not populated, connection refused/timed out, missing script/command, etc)
  • Event generation
    • No events under /Unknown
    • No exception/traceback events
    • Event mappings work
    • Events clear properly
    • No errors from Transforms
    • Transform load is minimal
  • Templates
    • Component templates are bound properly
    • Verify templates will scale (creating a datasource that runs once per component vs one per device)
    • Verify TALES in templates
  • Datasources
    • verify no exceptions/tracebacks during v10 runs (Sometimes these do not show in normal runs)
    • Does datasource create proper events on failures (and then clear)
Etc.
​
Tips/Tricks Examples:
  • Set trace in your code example (Here it is in the code, this is how it looks when you execute, tips like using dir() and dir(self))
  • How to set trace in jobs - (rdb.set_trace() example)
  • zentrap capture/replay for trap/mapping testing
  • Script that will export any template in Zenoss into yaml (I have one that is based around zpl code)
  • Breaking your zenpack.yaml into mutliple yamls for easy reading/editing
  • cProfile example (in transform and datasource)
Etc.

------------------------------
jstanley
------------------------------

Subject: RE: Intro + New Developer Docs
Author: Larry
Posted: 2019-04-09 16:12

Excellent points @Jay! ​I wonder if our custom ZPs are violating any of your tips (and how badly).

------------------------------
Larry
IPC Global
GA
------------------------------

Subject: RE: Intro + New Developer Docs
Author: Jay Stanley
Posted: 2019-04-11 10:31

It is a learning process. I look at my previous ZenPacks and wonder what I was thinking. And even now, each one I create or update I find better or easier ways of doing things..

------------------------------
jstanley
------------------------------

Subject: RE: Intro + New Developer Docs
Author: Adam McCurdy
Posted: 2019-04-11 15:08

Awesome, thanks a ton for this Jay. I'll be working on the developer docs more and more over the coming few weeks and this is definitely good stuff.

------------------------------
Adam McCurdy
Manager, Customer Enablement
Zenoss
------------------------------

Subject: RE: Intro + New Developer Docs
Author: Morgan Timney
Posted: 2019-04-13 09:38

Hey Adam (and all). 
The new site is nice, I sure hope it can be permanent. So often nowadays that just when you think you find an answer its a broken link :( . 
One of the first things I learned about websites is that you do not delete pages, you redirect to the new version.
There's much content (or at least subjects) in Janes guide that would be great to bring over to the new site. Like writing a command zenpack, converting command zenpacks to zenpython.

------------------------------
Morgan Timney
The Southern Company
Birmingham AL
------------------------------
  • Testing Installation
    • Verify install, verify removal (verify all objects that should be removed were)
    • When should you modify install() remove()
    • Best practices when modifying install() and remove()
    • Migration scripts
  • Negative Testing - How does your ZenPack components handle failures (wrong url, port, non-admin user, bad permissions, zProps not populated, connection refused/timed out, missing script/command, etc)
  • Event generation
    • No events under /Unknown
    • No exception/traceback events
    • Event mappings work
    • Events clear properly
    • No errors from Transforms
    • Transform load is minimal
  • Templates
    • Component templates are bound properly
    • Verify templates will scale (creating a datasource that runs once per component vs one per device)
    • Verify TALES in templates
  • Datasources
    • verify no exceptions/tracebacks during v10 runs (Sometimes these do not show in normal runs)
    • Does datasource create proper events on failures (and then clear)
Etc.
​
Tips/Tricks Examples:
  • Set trace in your code example (Here it is in the code, this is how it looks when you execute, tips like using dir() and dir(self))
  • How to set trace in jobs - (rdb.set_trace() example)
  • zentrap capture/replay for trap/mapping testing
  • Script that will export any template in Zenoss into yaml (I have one that is based around zpl code)
  • Breaking your zenpack.yaml into mutliple yamls for easy reading/editing
  • cProfile example (in transform and datasource)
Etc.

------------------------------
jstanley

Subject: RE: Intro + New Developer Docs
Author: Adam McCurdy
Posted: 2019-04-15 10:57

We're all-in on this new documentation strategy. You're definitely right about not removing pages -- it takes forever for search engines to reindex changes like that and the pain caused between those updates is definitely something we want to avoid. I've made it a point to bring that up with the team and we'll keep that in mind going forward. Thanks for the reminder.

------------------------------
Adam McCurdy
Manager, Customer Enablement
Zenoss
------------------------------


< Previous
Extend Monitoring Templates in child device classes 		  Next
Using ValueChangeThreshold type in ZenPack 		>