[Twisted-Python] Task-based documentation started

Tom Davis tom at recursivedream.com
Tue Feb 1 09:05:32 EST 2011


On Tue, Feb 1, 2011 at 3:44 AM, Albert Brandl
<albert.brandl at 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 at twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20110201/532f18e9/attachment.htm 


More information about the Twisted-Python mailing list