Ask HN: Back-end team does not document their APIs. How do I convince them?

Re:Ask HN: Back-end team does not document their APIs. How d... by cdnsteve on Tuesday October 11, 2016 @12:02PM (#12685645)

I've often found if you lead the effort yourself, and then ask for their input, this usually works well. If you wait for someone else to take the first step, it's usually not going to happen.

Start by creating a Github wiki for documentation for both front-end and back-end API's. Add them as collaborators, or create them right inside each existing repo if you can. Populate the back-end one as best you can to your knowledge, then ask for them to validate.

I always think of documentation as a note to my future self. In X months, what won't I remember?

[ Parent | on HN ]

Re:Ask HN: Back-end team does not document their APIs. How d... by afarrell on Tuesday October 11, 2016 @01:27PM (#12686475)

The problems I've found with this approach are:

1) It is hard to write clear explanations of things that you don't understand.

2) It adds another project to your plate. If you don't actually allocate time for this project from what you are currently doing, it won't get done well and it will distract you from what your primary responsibility is.

EDIT: So, OP would need to convince the product owner that he should spend his time on docs rather than javascript.

[ Parent | on HN ]