On Tue, Feb 1, 2011 at 3:44 AM, Albert Brandl <albert.bra...@weiermayer.com>wrote:
> On Mon, Jan 31, 2011 at 02:41:38PM -0500, Tom Davis wrote: > > Thoughts? > > I think that the overview in the first two sections is very good. It > made me curious to learn more. > > The "breadcrumbs" on the main page look like this: > "Contents :: Serving on the Web — HTML, CGI, WSGI, etc. » " > Might be a problem with the Sphinx configuration. > 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. > > Not sure about the link "read more about Twisted": There _is_ more about > Twisted on the rest of the page. When I clicked the link, I expected to > be redirected to twistedmatrix.com or something like this. Maybe you > don't need a link at this position at all. > 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. > > In the "Why Use Twisted" section, you write "Framework" - not sure if > this should be uppercased. But there are some other nouns (Tasks, > Project Documentation) that are written this way, so maybe it's Your > Way Of Emphasizing Things ;-). > > I'm also not sure if the explanation why I would use Twisted should be > in bold letters. Everywhere else you use italics. > > Do you intend to create a task description for connecting to an SSH > server (maybe with certificates)? This is something that whould have > been handy for me in the past. > Either create or expose one that already exists, yes. > > The "Everything Else" section should not contain links that are already > presented somewhere else. > 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. > > Do you intend to add some links to external pages here (e.g. the API > documentation or other web pages describing how to use the framework)? > Or should this documentation be self-contained? > API links will be common and will be under some reference/links area, I'm sure. It is very much a work in progress. > > One small usability quirk: The presentation of links in an orange, bold > font does not have much recognition value. I think it would be better to > use the standard way of marking links by using a blue, underlined font. > The same goes for links that have already been visited. > Again, this is a Sphinx template issue so we'll see how it changes with the actual Twisted one :) Thanks for the feedback! -Tom > > Best regards, > > Albert > -- > Albert Brandl > Weiermayer Solutions GmbH | Abteistraße 12, A-4813 Altmünster > phone: +43 (0) 720 70 30 14 | fax: +43 (0) 7612 20 3 56 > web: http://www.weiermayer.com > > _______________________________________________ > Twisted-Python mailing list > Twisted-Python@twistedmatrix.com > http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python >
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python