
<html><head></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><br><div><div>On Sep 18, 2010, at 5:59 PM, Matthew Sackman wrote:</div><br class="Apple-interchange-newline"><blockquote type="cite"><div>Sure, I understand what you're saying. I think it's reasonable to have<br>documentation a few revisions back, but if you then have a massive<br>rethemeing or rebranding exercise, do you really want to slog through<br>the 60 releases you've made over the last 5 years? There are maintanence<br>tradeoffs. E.g. you choose to rewrite a paragraph because it's not<br>clear. The functionality that the paragraph describes hasn't changed for<br>N revisions. Does the paragraph need applying to all N copies of the<br>documentation? I know these sound like trivial issues, but whatever<br>policy is agreed on should be applied consistently, and when you're in a<br>team of just 6 full time developers, these things take a substantial<br>toll on man power.<br></div></blockquote><div><br></div><div>Several years ago I started work on a CMS-like publishing app that would solve problems like this by handling content as paragraphs of text rather than as whole pages. I was trying to address this specific problem as well as provide streaming to browsers without having to download the whole page. Without anyone to help, though, it had to fall by the wayside. I still believe that a new publishing paradigm needs to be developed to put content on the Web 2.x that takes issues like this into account. But for the time being, a competent CMS combined with a fair bit of client-side code could provide a happy middle ground. Semantic CSS tags and jQuery would be sufficient to markup a page consistently, would be easy to change, and would be easy on the developers.</div><div><br></div><div>My hourly rate is quite cheap, BTW! ;)</div><br><blockquote type="cite"><div>By the same token, I hope you'll allow me to say that maybe OS X users<br>are equally skewed ;) </div></blockquote><div><br></div><div>No arguments there! In fact, I'd say OS X users are quite convinced their way is the best way. Present company included. ;)</div><br><blockquote type="cite"><div>I would agree that having<br>something like the Java API docs as man pages would be a horror show if<br>you didn't know what you were looking for, but being able to just type<br>"man HashTable" is _much_ faster than using a webbrowser.<br></div></blockquote><div><br></div><div>I recognize the truth in this but I still cringe at the thought. :) I guess I just prefer an HTML/web interface even though it's slower and probably more trouble in the end. They do put man pages on the web, too.</div><br><blockquote type="cite"><div>My only fear with that is that eventually people may get bitten by<br>missing features which were disabled simply because it would make<br>compilation more tricky. What is it about homebrew that you think will<br>prevent it from turning into macports again? Are they actively trying to<br>avoid supporting anything other than the simplest configuration of each<br>package?<br></div></blockquote><div><br></div><div>I don't see anything that would really prevent Homebrew from becoming MacPorts in a couple years. But I'm okay with that. I'll use it for a couple years and when it gets bloated I'll switch to the next thing that will inevitably come along to suit the minimalists. :)</div><br><blockquote type="cite"><div>I think the users should have the choice. Neither system offers that.<br></div></blockquote><div><br></div></div><div><span class="Apple-style-span" style="border-collapse: separate; color: rgb(0, 0, 0); font-family: Palatino; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-border-horizontal-spacing: 0px; -webkit-border-vertical-spacing: 0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; "><span class="Apple-style-span" style="border-collapse: separate; color: rgb(0, 0, 0); font-family: Times; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-border-horizontal-spacing: 0px; -webkit-border-vertical-spacing: 0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; "><span class="Apple-style-span" style="border-collapse: separate; color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-border-horizontal-spacing: 0px; -webkit-border-vertical-spacing: 0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; "><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><div><div><font class="Apple-style-span" face="Palatino" size="4"><span class="Apple-style-span" style="font-size: 14px; "><span class="Apple-style-span" style="font-size: medium;">Couldn't agree more.</span></span></font></div><div><font class="Apple-style-span" face="Palatino" size="4"><span class="Apple-style-span" style="font-size: 14px; "><span class="Apple-style-span" style="font-size: medium;"><br class="Apple-interchange-newline"></span>Thanks!</span></font></div><div><font class="Apple-style-span" face="Palatino" size="4"><span class="Apple-style-span" style="font-size: 14px; "><br></span></font></div><div><font class="Apple-style-span" face="Palatino" size="4"><span class="Apple-style-span" style="font-size: 14px; ">J. Brisbin</span></font></div><div><font class="Apple-style-span" face="Palatino" size="4"><span class="Apple-style-span" style="font-size: 14px; "><a href="http://jbrisbin.com/">http://jbrisbin.com/</a></span></font></div><div><font class="Apple-style-span" face="Palatino" size="4"><span class="Apple-style-span" style="font-size: 14px; "><br></span></font></div><div><font class="Apple-style-span" face="Palatino" size="4"><span class="Apple-style-span" style="font-size: 14px; "><br></span></font></div></div><font class="Apple-style-span" face="Palatino" size="4"><span class="Apple-style-span" style="font-size: 14px; "><br></span></font></div></span><br class="Apple-interchange-newline"></span><br class="Apple-interchange-newline"></span>

</div>

<br></body></html>