I have been wondering why so many coders have bad organization in their documents.
I think I know why.
As usual it has to do with standardization. If no standard it out there, everyone has to reinvent the wheel all the time.
So I upload a gem at RubyGems.org. But that was only 1/4 of it all.
- I have to write a tutorial for it, making categories, text style, size, color etc
- I have to generate API documentation from my code
- I have to put it in Git-hub (never done this, but that should be correct?)
It’s a painful process.
Wouldn’t it be great if every gem followed the same documentation structure. You upload your gem, you write a documentation for it that everyone can edit, the API documentation has been generated too, maybe created automatically, if you provided your account information for example.
A good process.
I think that would boost up good collaboration and environment than every gem has its own structure (bad documentations) and putting API documentation here and there.
Don’t you agree?
This kind of documentation (tutorial, non-generated doc, …) is better addressed by a wiki.
Most of the public source container out there now integrates one in their features.
GitHub recently improves its own wiki system.
It also proposes GitHub pages (for publishing content to the web by simply pushing content to one of your GitHub hosted repositories, with user pages or project pages, and with Jekyll for even more Makdown file formats)