On Sun, Jan 24, 2010 at 17:12, Philip Olson <phi...@roshambo.org> wrote: > > On Jan 24, 2010, at 3:25 AM, Hannes Magnusson wrote: > >> On Sun, Jan 24, 2010 at 07:09, Daniel Convissor >>> Personally, I like the history being there. It is interesting to see how >>> things evolve. Having this data there does no harm to anyone. >> >> I don't like inline history. >> >> If we can create a standardized changelog for all features, I think >> that would solve everything. >> Things like "As of PHP 4.3.0 PHP ships with a CLI[...]" >> (php.net/commandline) could be moved to a changelog "4.3.0 - PHP CLI >> was introduced" and that line could become "PHP ships with a CLI[..]". >> Or we could even add version information (like with functions) at the top? > > Another great example that shows how difficult it can be to read > documentation that's littered with version history. The CLI docs border on > being unreadable. > > We don't have a nice way to list changelog history yet (for non-functions) > but it seems possible. A table? Adding version information on top feels > difficult considering all the different changes. Like for CLI, was it born > with 4.3 or 4.2? Difficult to say, but an explicit changelog would clear that > up. >
Adopting the function changelogs seems like the simplest way the the added sideaffect of giving a consistent look. -Hannes
