DesignWIKI

Fil Salustri's Design Site

Site Tools


wiki:refactor_by_extracting_to_page

Refactory by Extracting to Page

Problem: A page is getting too long and is getting too difficult to understand.

There are four possible solutions.

Move parts of the page to new pages: This is probably the safest way to refactor a page, since the original content can be stored safely and accessibly, while also keeping pages organised.

  • Indicated when the part to be moved is a (nearly) self-contained chunk.
  • The danger of only a naive splitting of one long page into a bunch of sub-pages is that the gestalt of the original page is lost.
  • Leaving just a link to the new page in the original page is rarely a good idea. Better to put brief explanatory text with that link.
  • General suggestion for moving text:
    1. Start edit sessions on both old and new pages.
    2. Cut & paste a chunk from the old page to the new one.
    3. Immediately replace the cut chunk in the old page with a link to the new page, and a brief explanation.
    4. Repeat as required, creating new pages as required, until all unrelated chunks in the old page have been moved.

Move discussion (cf. discussion mode) to a separate page from conclusions: Once a discussion starts to wind down:

  • move the discussion to a separate page, and refactor by backlinking.
  • add a reference to the new page in the current page (plus optional explanation of the move).
  • replace the discussion with a summary of the real content. (cf. refactor by summarising)

Replace long chains of thought with summaries: A long, rambling presentation of an argument may unnecessarily detract from the presentation of content in a page.

  • Move the detailed argument to a separate page, leave only a summary, and provide appropriate links back and forth.

Identify and separate tangents: A tangent is a side discussion that takes on a life of its own.

  • Move tangents to their own pages, leaving a link to the new page in the original page.
wiki/refactor_by_extracting_to_page.txt · Last modified: 2020.03.12 13:30 (external edit)