Hacker News new | past | comments | ask | show | jobs | submit login

I've found writing documentation and trying to explain to others why the API is the way it is frequently makes me completely reconsider and redesign the API to be better. So no, you really should start on documentation right away, because what you're calling "waste" right now is a feature.



That is interesting, I think the way I do it is quite similar: normally I write the examples that would go in the documentation first then work around it, but I don't write the whole text+proofreading which is what takes most of the time for me.

Edit: see this "others" folder for example: https://github.com/franciscop/server/tree/master/others


That does help, but I've found that getting people to try using your API does an even better job of informing you about your design decisions.

Last time I was building a novel API, I opted to provide commented example code for documentation, recruited several members of the intended audience to try out the API, and just offered to answer questions directly. I wrote out actual documentation in preparation for the "official 1.0 release."

At some point it comes down to choosing how to spend your limited time. Writing documentation isn't going to be a "waste," but it's probably not high ROI because your early adopters are likely familiar with the problem domain anyway.


Oh cmon I never ever said writing documentation is a waste!

What I mean is that writing the final documentation with all that implies before you even know what the API is going to look like is a waste. Though I agree with the parent, stubbing some docs to get a better feeling of what the docs look like is valuable.




Consider applying for YC's Spring batch! Applications are open till Feb 11.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: