Opened 6 years ago

Closed 6 years ago

#5427 enhancement closed fixed (fixed)

Improve core documentation index page

Reported by: Itamar Turner-Trauring Owned by: Itamar Turner-Trauring
Priority: normal Milestone:
Component: core Keywords: documentation
Cc: jesstess, Thijs Triemstra Branch: branches/howto-index-5427-2
branch-diff, diff-cov, branch-cov, buildbot
Author: itamarst, itamar

Description

The core howto documentation is badly organized, and could do with some descriptions and explanations.

Change History (15)

comment:1 Changed 6 years ago by itamarst

Author: itamarst
Branch: branches/howto-index-5427

(In [33312]) Branching to 'howto-index-5427'

comment:2 Changed 6 years ago by Itamar Turner-Trauring

Author: itamarstitamar
Keywords: review added

comment:3 Changed 6 years ago by jesstess

Cc: jesstess added
Owner: set to jesstess

comment:4 Changed 6 years ago by jesstess

Keywords: review removed
Owner: changed from jesstess to Itamar Turner-Trauring

Thanks for working on this, itamar. Your changes look good; feel free to deploy now if you want, but a few comments:

  • "Network programming should be easy... and fun!" It's hard for me to read this with a straight face.
  • Is "Test-driven development with Twisted" the third document new users should be reading, after servers and clients? Would the intro to Deferreds be better? Or perhaps TwistedQuotes, which is a short application example then followed by the longer Finger tutorial?
  • I'd prefer that the Legacy Documentation not be referenced in the index at all, rather than listed but saying it is broken. We can remove those links and open tickets to either reintroduce updated documentation or remove those documents altogether.

comment:5 Changed 6 years ago by Itamar Turner-Trauring

  1. Is this a good thing or bad thing? I do want this to be entertaining.
  2. I think test-driven development should be pretty central, because that's one of the big wins with Twisted: the ability to test your network code. It's also good marketing for more experienced developers. Moreover, the testing tutorial only adds reactor.callLater to the knowledge from the previous two howtos, and repeats the explanations of factory/protocol etc., so I think it's a reasonable next step.
  3. Will do.

Another requirement before resubmitted for review: reorganize book.tex to match the new index.

comment:6 Changed 6 years ago by itamarst

Author: itamaritamarst, itamar
Branch: branches/howto-index-5427branches/howto-index-5427-2

(In [33413]) Branching to 'howto-index-5427-2'

comment:7 Changed 6 years ago by Itamar Turner-Trauring

Keywords: review added
Owner: Itamar Turner-Trauring deleted

OK, I removed two bad howtos, moved telnet howto out of legacy since it can be salvaged (the functionality still exists in non-deprecated form in twisted.conch), updated book.tex (there were *lots* of missing howtos!).

Buildbot documentation slave is happy: http://buildbot.twistedmatrix.com/builders/documentation/builds/1792

comment:8 Changed 6 years ago by jesstess

Owner: set to jesstess

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

Thanks. Documentation tickets are super important, we need to keep doing stuff like this.

  1. The graphical overview doesn't strike me as particularly useful. Also, it's full of incorrect information. We have another ticket for updating it which people have been avoiding working on for ages. Should we take this opportunity to drop the "document"?
  2. It's true that conch provides telnet functionality, but it's not API compatible (at all) with twisted.protocols.telnet, deprecated since Twisted 2.1, which is what the telnet howto documents. We really just need a new howto for the conch telnet library.
  3. I am a little bit uneasy about all the new claims of "easy" things in the index. Good documentation shows you that things are easy, it doesn't tell you that they are. +1 on being entertaining, but claiming everything is easy here looks bad to me. It's one of the things that made deferredindepth.xhtml such a terrible document and worthy of deleting here.
  4. Here's some scope creep for you. The "low level" section of the index doesn't make a lot of sense to me. SSL, endpoints, and processes are low-level? Not really. SSL and processes are just features you might want, and inasmuch as we're talking about Twisted APIs here, these APIs are probably pretty high-level compared to what a reader is used to, or what they might find elsewhere. And on top of that, endpoints are the highest-level connection setup API Twisted has.

I don't have the tools to build the book on hand. I'll assume you've tested this yourself and it still works and looks proper. Please merge when you've addressed the above points to your satisfaction (unless jesstess has anything to add :). Thanks!

comment:10 Changed 6 years ago by jesstess

Keywords: review removed
Owner: changed from jesstess to Itamar Turner-Trauring

comment:11 Changed 6 years ago by Thijs Triemstra

Cc: Thijs Triemstra added

It also looks like there are example listings files that were referenced in the deleted core/howto/deferredindepth.xhtml that can now be deleted.

comment:12 Changed 6 years ago by Thijs Triemstra

\input{../specifications/banana.tex} was also removed from the book.tex for some reason.

comment:13 Changed 6 years ago by Itamar Turner-Trauring

Keywords: review added
Owner: Itamar Turner-Trauring deleted

Review comments have been addressed:

  1. Deleted overview and images, added 1712.misc for that ticket, #1712.
  2. Deleted telnet.
  3. Rewrote the bits about easiness.
  4. Renamed that sections to "Networking and Other Event Sources", and moved endpoints to high-level infrastructure.
  5. Deleted deferred in depth code listings.
  6. I removed banana spec on purpose - it's not on regular howto index, and I doubt people looking at book-like PDF actually want it either.
  7. I also made a few more minor edits, e.g. the tutorial section is now "Getting Started".

Buildbot for docs: http://buildbot.twistedmatrix.com/builders/documentation/builds/1806

comment:14 Changed 6 years ago by jesstess

Keywords: review removed
Owner: set to Itamar Turner-Trauring

This is a tremendous improvement over the existing index -- thanks for working on this. Please merge!

comment:15 Changed 6 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.