<div class="gmail_quote">On Tue, Feb 1, 2011 at 3:44 AM, Albert Brandl <span dir="ltr"><<a href="mailto:albert.brandl@weiermayer.com">albert.brandl@weiermayer.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im">On Mon, Jan 31, 2011 at 02:41:38PM -0500, Tom Davis wrote:<br>
> Thoughts?<br>
<br>
</div>I think that the overview in the first two sections is very good. It<br>
made me curious to learn more.<br>
<br>
The "breadcrumbs" on the main page look like this:<br>
"Contents :: Serving on the Web — HTML, CGI, WSGI, etc. » "<br>
Might be a problem with the Sphinx configuration.<br></blockquote><div><br></div><div>Yeah, this is just how the Sphinx template lays things out and it's the default one I use for documentation on my site, merely because the color scheme is similar. It's definitely not the greatest and a Twisted-theme one already exists so we'll be working from that.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<br>
Not sure about the link "read more about Twisted": There _is_ more about<br>
Twisted on the rest of the page. When I clicked the link, I expected to<br>
be redirected to <a href="http://twistedmatrix.com" target="_blank">twistedmatrix.com</a> or something like this. Maybe you<br>
don't need a link at this position at all.<br></blockquote><div><br></div><div>Well, that was originally going to lead to some history/about stuff, but looking at it again that doesn't seem like an initially great use of time.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<br>
In the "Why Use Twisted" section, you write "Framework" - not sure if<br>
this should be uppercased. But there are some other nouns (Tasks,<br>
Project Documentation) that are written this way, so maybe it's Your<br>
Way Of Emphasizing Things ;-).<br>
<br>
I'm also not sure if the explanation why I would use Twisted should be<br>
in bold letters. Everywhere else you use italics.<br>
<br>
Do you intend to create a task description for connecting to an SSH<br>
server (maybe with certificates)? This is something that whould have<br>
been handy for me in the past.<br></blockquote><div><br></div><div>Either create or expose one that already exists, yes.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<br>
The "Everything Else" section should not contain links that are already<br>
presented somewhere else.<br></blockquote><div><br></div><div>These are ToC trees which are different from inline links. I don't feel there's much harm in linking to something twice on one page especially when the same words are used and one of the uses is clearly a ToC.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<br>
Do you intend to add some links to external pages here (e.g. the API<br>
documentation or other web pages describing how to use the framework)?<br>
Or should this documentation be self-contained?<br></blockquote><div><br></div><div>API links will be common and will be under some reference/links area, I'm sure. It is very much a work in progress.</div><div> </div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<br>
One small usability quirk: The presentation of links in an orange, bold<br>
font does not have much recognition value. I think it would be better to<br>
use the standard way of marking links by using a blue, underlined font.<br>
The same goes for links that have already been visited.<br></blockquote><div><br></div><div>Again, this is a Sphinx template issue so we'll see how it changes with the actual Twisted one :)</div><div><br></div><div>Thanks for the feedback!</div>
<div><br></div><div>-Tom</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<br>
Best regards,<br>
<br>
Albert<br>
<font color="#888888">--<br>
Albert Brandl<br>
Weiermayer Solutions GmbH | Abteistraße 12, A-4813 Altmünster<br>
phone: +43 (0) 720 70 30 14 | fax: +43 (0) 7612 20 3 56<br>
web: <a href="http://www.weiermayer.com" target="_blank">http://www.weiermayer.com</a><br>
</font><div><div></div><div class="h5"><br>
_______________________________________________<br>
Twisted-Python mailing list<br>
<a href="mailto:Twisted-Python@twistedmatrix.com">Twisted-Python@twistedmatrix.com</a><br>
<a href="http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python" target="_blank">http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python</a><br>
</div></div></blockquote></div><br>