So I spend this weekend writing up some documentation for the flexbillet-api. I have done no research what-so-ever, and this makes for a nice point!
While not-researching, I actually wrote some documentation. My thoughts kept coming back to "there must be a tool to automate some of this", but instead of exploring, or even start writing something up, I just did it. And there it is: https://github.com/nwillems/node-flexbillet-api
So why was the documentation important? 1. It would suck to put something out there, and then have nobody able to use it, 2. The feels - giving something back, and then proudly publishing to NPM. Yes its on NPM, this little gem(ahem..), https://www.npmjs.com/package/flexbillet-api
This is my first published module on NPM and it feels really great. Thinking about it, it seems completely unreasonable, but it feels good.
So the actual documentation, if you look at the commit history I did quite some iterations. Recently I've been introduced to squashing commits, but this time I felt that it would defeat the purpose. It sort-of documents the documentation process. The documentation is split in three parts: Installation, Simple usage and reference docs.
The installation is easy, it is also the shortest part, it also makes a lot of assumptions, you should be somewhat familiar with the terminal and the node ecosystem, or at least be able to translate it.
The "simple usage" is the most straight forward part, also the hardest part for me to write, simply put it should boil down the module to a single piece of code that shows you that it works, something you could copy-paste and have working within 5-minutes. I think it succeeds in that.
Finally the "reference doc" should be a comprehensive list of the methods provided and their expected behaviour. This is the time-consuming part to write, first ensure that the method is tested(and fails), then implement it correctly, then have the test produce output, now add the inputs and outputs to the documentation, factor out common objects(See Generally defined objects), and lastly contemplate wether you should start an effort to structure the returned output differently, or maybe make it more of an exploration for the user...
And this is where I leave you, with a list of next weeks topic - testing.
EDIT: This post should have had a GIANT kudos to the NPM people, https://docs.npmjs.com/ is an awesome site, I never thought it would be so easy to publish something to NPM. Awesome job guys!
While not-researching, I actually wrote some documentation. My thoughts kept coming back to "there must be a tool to automate some of this", but instead of exploring, or even start writing something up, I just did it. And there it is: https://github.com/nwillems/node-flexbillet-api
So why was the documentation important? 1. It would suck to put something out there, and then have nobody able to use it, 2. The feels - giving something back, and then proudly publishing to NPM. Yes its on NPM, this little gem(ahem..), https://www.npmjs.com/package/flexbillet-api
This is my first published module on NPM and it feels really great. Thinking about it, it seems completely unreasonable, but it feels good.
So the actual documentation, if you look at the commit history I did quite some iterations. Recently I've been introduced to squashing commits, but this time I felt that it would defeat the purpose. It sort-of documents the documentation process. The documentation is split in three parts: Installation, Simple usage and reference docs.
The installation is easy, it is also the shortest part, it also makes a lot of assumptions, you should be somewhat familiar with the terminal and the node ecosystem, or at least be able to translate it.
The "simple usage" is the most straight forward part, also the hardest part for me to write, simply put it should boil down the module to a single piece of code that shows you that it works, something you could copy-paste and have working within 5-minutes. I think it succeeds in that.
Finally the "reference doc" should be a comprehensive list of the methods provided and their expected behaviour. This is the time-consuming part to write, first ensure that the method is tested(and fails), then implement it correctly, then have the test produce output, now add the inputs and outputs to the documentation, factor out common objects(See Generally defined objects), and lastly contemplate wether you should start an effort to structure the returned output differently, or maybe make it more of an exploration for the user...
And this is where I leave you, with a list of next weeks topic - testing.
EDIT: This post should have had a GIANT kudos to the NPM people, https://docs.npmjs.com/ is an awesome site, I never thought it would be so easy to publish something to NPM. Awesome job guys!
No comments:
Post a Comment