Opened 14 years ago

Closed 8 years ago

#1712 defect closed fixed (fixed)

Twisted overview graph shows Xish

Reported by: ralphm Owned by:
Priority: normal Milestone:
Component: core Keywords: documentation
Cc: Jean-Paul Calderone, Thijs Triemstra, radix, Tom Davis Branch: branches/overview-graph-1712
branch-diff, diff-cov, branch-cov, buildbot
Author: thijs

Description

The graphical overview at http://twistedmatrix.com/projects/core/documentation/howto/overview.html still shows Xish as a separate component. However, it has been folder into Words a while back.

Attachments (1)

graphical-overview.svg (20.8 KB) - added by Jean-Paul Calderone 9 years ago.

Download all attachments as: .zip

Change History (23)

comment:1 Changed 14 years ago by Jean-Paul Calderone

Keywords: documentation added
Owner: changed from Glyph to Nicola Larosa

comment:2 Changed 14 years ago by Jean-Paul Calderone

It also shows Twisted.Flow, Twisted.Protocols as containing all the protocol implementations, half the executables in the wrong place, and implies "String ports" is a fundamental part of core twisted. Basically half this picture is wrong. The whole thing needs a going over.

comment:3 Changed 14 years ago by ralphm

Cc: Jean-Paul Calderone added

Would 2.3 be a good target for this?

comment:4 in reply to:  2 Changed 11 years ago by Thijs Triemstra

Cc: Thijs Triemstra added

Replying to exarkun:

Basically half this picture is wrong. The whole thing needs a going over.

Are the source files for those diagrams available?

comment:5 Changed 11 years ago by Jean-Paul Calderone

There's doc/core/img/twisted-overview.dia, that's probably it.

comment:6 Changed 11 years ago by Thijs Triemstra

Owner: changed from Nicola Larosa to Thijs Triemstra
Status: newassigned

comment:7 Changed 11 years ago by Thijs Triemstra

Author: thijs
Branch: branches/overview-graph-1712

(In [25338]) Branching to 'overview-graph-1712'

comment:8 Changed 11 years ago by Thijs Triemstra

Keywords: review added
Owner: Thijs Triemstra deleted
Status: assignednew

Removed xish and flow from the diagram in r25339, I'll need a better description/suggestion to restructure the diagram. Putting it up for review.

comment:9 Changed 11 years ago by ralphm

Your change indeed fixes the problem described in this ticket. Is your question whether this diagram should have more changes? I think so. Should it go into this ticket? I'd agree on widening the scope of this ticket.

comment:10 Changed 11 years ago by Jean-Paul Calderone

Keywords: review removed
Owner: set to radix

Yes. The diagram still needs a lot of work. Even with xish in the right place now, it doesn't really convey useful information to someone trying to learn about Twisted. It's just a bunch of boxes and words and arrows.

We could remove it entirely or someone who's familiar with the various abstractions in Twisted could try fixing it (perhaps by starting over from scratch) to be useful.

A couple other specific problems with the current form:

  • it includes mktap, which we've stopped documenting anywhere else
  • it talks about bin/lore instead of bin/lore/lore

There are doubtless other issues, but those are the two which I noticed first. Even if these are fixed, the diagram is still not useful (but the problems shouldn't be replicated in any future version).

As a roughly orthogonal issue, dia doesn't seem like the best format we could use for this kind of thing. I'd suggest svg for a future version (but whatever).

Speculatively reassigning this to someone who might fall into the familiar with the various abstractions in Twisted group.

comment:11 Changed 10 years ago by Thijs Triemstra

Cc: radix added
Keywords: review added

Assigning to radix for review then.

comment:12 Changed 10 years ago by radix

Keywords: review removed
Owner: radix deleted

I'm not sure what I'm supposed to be reviewing here. It looks like this ticket is in need of implementation before I can review it.

comment:13 Changed 10 years ago by Thijs Triemstra

Owner: set to Thijs Triemstra
Status: newassigned

Let's include exarkun's suggestions and then hopefully merge:

  • it includes mktap, which we've stopped documenting anywhere else
  • it talks about bin/lore instead of bin/lore/lore

comment:14 Changed 10 years ago by Jean-Paul Calderone

Other things that are wrong with the diagram:

  1. twisted.protocols no longer contains any of the protocols it talks about (except telnet, which is deprecated). Instead it should actually be listing at least some of the stuff (ftp and socks, anyway) from the "Other" box in the "Twisted.Servers" section.
  2. "Twisted.Servers"? What does that mean? Those look like more "Twisted Subprojects", except for "Other", which I think we should just drop.

comment:15 Changed 9 years ago by Thijs Triemstra

I suggest we redo it in .svg so it can be opened in other programs besides Dia, which doesn't allow me to edit the text in the trunk's file.

comment:16 Changed 9 years ago by Tom Davis

Cc: Tom Davis added
Owner: Thijs Triemstra deleted
Status: assignednew

If redoing this is underway or even the preferred method, might a sufficient resolution for this ticket be to remove the existing diagram from the documentation since the prevailing opinion seems to be that it isn't accurate or useful enough to do anything but confuse viewers? Then a redo could be undertaken as a different ticket with a preliminary number of corrections.

I don't know if flagging this for review is the right thing here, but the ticket seems to be at an impasse and the "Graphical Overview" is still the second link under /core/howto/ so the "path to resolution" should be decided.

comment:17 Changed 9 years ago by Tom Davis

Keywords: review added

comment:18 Changed 9 years ago by Jean-Paul Calderone

Keywords: review removed

I started working on an SVG version of the overview (not really based on the existing one, which I don't think makes any interesting or informative organizational decisions). Attached is the results of my efforts up to the point where I realized there's no way I'd actually finish it.

Removing the review keyword because there's still nothing to review here. Someone needs to make some graphics, then there'll be something to review.

I don't think deleting the overview just so we can close a ticket is the right thing to do, though. On the other hand, if someone wants to argue that a graphical overview isn't a useful part of the documentation, feel free (to argue that).

Changed 9 years ago by Jean-Paul Calderone

Attachment: graphical-overview.svg added

comment:19 in reply to:  18 Changed 9 years ago by Tom Davis

Replying to exarkun:

I don't think deleting the overview just so we can close a ticket is the right thing to do, though. On the other hand, if someone wants to argue that a graphical overview isn't a useful part of the documentation, feel free (to argue that).

I didn't mean to argue that a graphical overview doesn't have the potential to be a useful part of the documentation, merely that prevailing wisdom suggests the current one is not. If something is uninformative at best and misleading at worst, it should probably just be removed until it's in a position not to do damage. Whether or not anybody else shares my opinion is another matter!

comment:20 Changed 9 years ago by <automation>

comment:21 Changed 8 years ago by Thijs Triemstra

#5432 was marked as a duplicate.

comment:22 Changed 8 years ago by itamarst

Resolution: fixed
Status: newclosed

(In [33453]) Merge howto-index-5427-2.

Author: itamar Review: jesstess, exarkun, thijs Fixes: #5427, #1712

The core howto index has had many crufty howtos removed, and has been reorganized. Also, the generated PDF should now contain all howtos (it was missing some).

Note: See TracTickets for help on using tickets.