Or trying. We, as developers, love code. We read, we study, we do stare at a nice code and get amused by it. In the end of the day what we really care about is code and its functionality. Making our work useful is always the main objective and to do that, we have to - let me take a deep breath here - document it.
We have solutions today that circle around documentation blocks for classes, methods, properties and so on. We even made that documentation do something with @Annotations. So we code and (hopefully) document it using an specific markup: PHPDoc.
Don't get me wrong here. I really think PHPDoc is great, but the documentation generated by it is really usefull? Yeah, I know: IDEs do use them and so on. But how many times have an API doc been useful? Can you just give an API doc to someone and expect a lot of understanding from it?
Open source has a hude debt to GitHub in many points, making READMEs useful again is just one of the many points. Using Markdown as a common ground is another point, it is a markup language with a simple and humble objective: make it readable by humans.
Readme made components really simple to use and play with. It usually holds all the sensible information of a project and (if you are lucky) provides you with some examples to get you going. In few words, it is awesome!
As with anything, there are not only good things about them. As with any documentation, they have to be up to date. And man, that is lame. I may don't know you, but I can speak for myself: I hate keeping a readme up to date. After adding that awesome thing or fixing it - who knows - going back to the readme and writing the changes just doesn't feel right. Just doesn't.
We could discuss forever on this and have people staring at us with disgusting eyes if you are in a crowded bar having some beer. But let's try to have a common ground here. We all have our manners and conclusions on good code, but no one (and I am making a guess here) will say tested code is bad.
You can have a huge-misleading-awfull code and (good) tests will make that code berable. If anything, you know that the whole mess is still working or breaking (that is important) in the way your application expects. That makes you sleep at night and, who knows, take some vocations sometime.
Documenting awfull code is not going to fix it, testing will somewhat put the beast to sleep. Like someone (wise) said someday:
"Crap code, documented, still smells like crap." (Wise man unkown by be)
Simple answer: the API.
It stands for "Application Programming Interface", it is the way different components communicate with each other.
Within components we have some way to use it. Some class to instantiate, something to call. An entry point. How can we define them? It is easier than it sounds, just look for public things (methods, properties) ignoring abstract classes. That's what you are going to work with, that's is the component API.
I wish you luck on this, because you can always get into the static stuff and if that doesn't feel wrong to you now, take my word and belive me: it will.
So we have some points:
- Markdown and readme are a great couple
- Good code is tested code
- The minimum desired documentation is the API
With that points in mind, me and @alganet came up with what (still) seems a good idea: let's generate the readme.md using the component api and it's tests.
We quickly created the Respect\Doc class that generates the documentation for itself and hopefully for all other projects we love to have. The class receives a class or a namespace and starts finding things to document, it searches for public and static stuff and parses it's PHPDoc as the documentation.
Examples, of course we want them! What are we still missing? The tests. All the examples for Doc are taken from the unit tests we coded for it. It searches for specific methods unit tests and appends the code from these tests in the end of the documentation for that method.
We are not trying to replace PHPDoc. We are trying not to fall on the "keep the documentation up to date" thing. We know the limitations on our aproach and we are happy with them if it still generates a good readme.md to people get started with our code.
Of course Doc has a lot of room for improvement. It misses some sensible features that we need to code so we can use it on another Respect projects, but while that is happening, would be wonderfull to hear some feedback from you.
It already works nicely for us, but would't be awesome if it also worked for people that (like us) hate keeping the project documentation? We think it would, and we would love some feedback on that.
A couple of typos but the content is awesome. Though we need better working samples before posting this. Having all of our docs by Doc would do.