Re: Version documentation... Re: [PEAR-DOC] Is your package really documented? The truth

Klaus Guenther wrote:

OK... big question... I'm about to release HTML_Page2. HTML_Page is not documented. Should the documentation be classified under HTML_Page or HTML_Page2? It is possible that people will stick to individual versions (e.g., if MDB2 == DB_v2, then replacing the DB docs would be foolish). However, I'm not going to release docs for HTML_Page. That will remain as-is. And I'll only document my 2.x series. On the other hand, documenting each version will in many cases be overkill and if devs are having a hard time documenting their packages the way it is, you can forget about them writing multiple documentations.

Hopefully, the design is good enough that an update to HTML_Page3 will not require much change. However, once you go to HTML_Page3, HTML_Page2 is deprecated, so you can even drop the documentation maintenance. I would put the docs under HTML_Page2, and then when/if HTML_Page3 comes out, make a small manual stub that only describes any differences and refers users to the docs for HTML_Page2. For now, if you are feeling feisty, you could do a single HTML_Page doc that refers to HTML_Page2, or just mention on the first page of HTML_Page2 that it documents HTML_Page, which is deprecated (my choice, if I was making it). Let's use as much common sense (end-user sense?) as possible in this, so if you have a better idea, then do it. Greg