Tags:
brainstorming1Add my vote for this tag create new tag
, view all tags
There are two implementation strategies available for this request:
  • PeterKlausner implemented a method that simply pulls out the beginning of the topic for use as an ad-hoc summary requiring no new mark up or effort on the part of the user.
  • MS implemented a method whereby a user denotes the beginning of a summary using %SECTION{summary}% / %ENDSECTION% tags as part of NamedIncludeSections. These named sections can now fail over gracefully as part of interpretted search formats in the chaos branch of owiki allow WebChanges and WebIndex to include user defined summaries in those (and other) search results - making both changes and index significantly more useful. People who want to back port the feature should feel welcome to do so. (Subject to usual caveats of TWiki's releases must at least try to have a valid copyright file) -- MS, Nov 2003
  • MartinCleaver commented that this is simply meta data and so new new mechanisms need be invented. 28 Sep 2004.

The two approaches are complementary, and not mutually exclusive. Peter's patch is attached to this page, Michael's patch is attached to named include sections. -- MichaelSparks - 14 Jun 2003

Summary:
This topic explores alternative options for designating and displaying a topic summary. The current default is simply the first 162 characters in a topic. The discussion has identified three different kinds of page summaries that deserve different treatments. These are:
  • Executive summary - Provides overview of a topic. This summary is an example. Current idea is to define variables that bracket text to designate and display summary similar this one.
  • Short "lead-in" summary - Using tags to select out a text string anywhere within the text of topic that provides a short summary of the topic that can be included in FormattedSearch and WebNotify emails. Current thinking is that this will require some programming to define tags and provide for inclusion in WebNotify.
  • "Headline" or recent change summary - To highlight or comment on recent changes. This would be included in FormattedSearch and WebNotify email to facilitate tracking topic changes. Current thinking is that this could be implemented with a form field. Programming needed to include in WebNotify.

(This summary is just my sense of discussion thus far and is offered as an example of putting these ideas into practice. I invite others revise it as you see fit and as discussion progresses). -LB

All this and more can be achieved with NamedIncludeSections - MS (justication of comment)

[Main.PeterMasiar, 02 Jun 2002:] Of course, real Executive summary on the top of the page should be shorter, max couple of paragraphs, like:

Summary:
Different opinions about what kind of summary we want, and for what usage:
  • Executive summary: almost static text (like this one), entered close to page top. (Possible implementation)
  • Short "lead-in" summary: Using new tags, picked from anywhere in the page(?), but static.
  • "Headline" or recent change summary: about reasons for page changes, maybe displayed in WebNotify.

IMHO we should not explain detail of implementation, or even where results will be used, right in the summary - we have whole page for that smile Link to details is allowed, but not more.

Following is original (IMHO too long) summary from LynnwoodBrown:

(I've moved it back to the top. Many people just read summaries/abstracts - they should stand alone if necessary. Feel free to move back. MichaelSparks 12 June 2003)

To be fair to LynnwoodBrown, I don't think he tried to write an "executive summary" -- he was just trying to summarize the discussion "to that point" as an aid to further discussion / consensus building. -- RandyKramer - 03 Jun 2002



Currently TWiki takes approximately the first 162 characters of a topic and uses it as a summary in things like the WebChanges page and the summary used in the display of a search.

I would like to make two RFEs:

  1. Provide TWiki tags to markup (designate) a specific section of text to be treated as the summary (instead of the first 162 characters). It might be appropriate to enforce a limit on the summary, limiting it to, for example, 162 (displayed) characters even if more than that are included in the designation.
  2. Provide a similar mechanism to designate a short summary of the most recent revision of a page and allow it to optionally be included on things like the WebChanges page and the summary used in search results. I'd expect these to be one-liners, limited to perhaps 80 characters.

I am marking this as a brainstorming item, because I'd like to consider expanding the request -- it may be useful to:

  • Maintain all old revision summaries and display them under certain circumstances

For example, we might even modify the WebNotify email (and page?) to display the summaries for all the revisions which occurred in the previous 24 - 48 hours, so if multiple revisions occurred, you'd see a brief summary of each.

These further enhancements could help deal with the problem of revisions due to page name changes and other such trivia.

-- RandyKramer - 09 Apr 2002

Flexible page summary is discussed at WhatIsTopicSummary in Support web. Simple solution was to put it into table and then look for | at start of page text, like:

Summary: What is this page about?

It will be nice to have summary table across whole page, centered, 90%. Not sure how to do that. frown

-- PeterMasiar - 10 Apr 2002

Interesting -- I had read that page earlier but I missed the notes at the bottom.

I guess LynnwoodBrown captured my thoughts in this:

The TopicSummary does not completely fulfill this for me as most people are not necessarily conscious of the first n characters they write in a topic being the summary. Sometimes it is and sometimes it may not be. Considering this topic for example, my opening line is definitely not a good summary. I suspect a lot of people start out writing like in an email where the first line or two is just sort of a warm-up to the real topic.

He plans to make more of an effort to make the first 162 characters a good summary. A good idea, but I would like to allow a gentle introduction before the summary. With the suggestion made on this page, someone can write a sentence or two of gentle introduction, then 162 characters of summary, all in the same font and format. The summary markup would pick up the sentences intended to be the summary.

-- RandyKramer - 10 Apr 2002

Randy - I was delighted to see your comments here. You went further in articulating what a really useful topic summary would look like. I had not thought of the usefulness of being able to see updated topic summaries as a topic evolves but I see that would a significant enhancement to the ease of tracking topics!

In regards to implementation schemes, what I really meant to attempt through use of a standard expression was not simply using the first ~162 characters but selecting out of that some shorter portion, like up to the first period. Going a step further, my interest in Peter Thoeny's example of a FormattedSearch was the ability to select the text between a header (e.g. "Summary) and the next period. This would be one way to achieve your suggestion of "markup tags" to designate the topic summary anywhere in the topic. Either putting the header "topic summary" into a topic template, or including a table as per Peter Masiar's suggestion, would provide the user clear prompting about where to put the topic summary.

I also agree with you about allowing a short section before the topic summary. This is the format used in most pattern languages (see OrgPatterns:PatternTemplate) which represents my "ideal" topic format. In that case, the "context" is the warm up to the topic summary. In a sense, most opening comments in emails serve that same purpose: to provide a context for the particular topic at hand.

Anyway, I was glad to see someone else thinking in the same direction. It would be great to see the more robust enhancement you suggest but for now my needs would be met simply by figuring out a search standard expression using the the "pattern" variable to search for the text between "summary" and the next period. Or, it occurs to me now that you could use the pattern variable to implement your "tagging" scheme" by searching for the text between two hidden text strings. Now if I can just get the time to study construction of standard expressions enough to figure out how to do this...

-- LynnwoodBrown - 11 Apr 2002

Lynnwood,

Thanks for your comments -- yes I agree that it may be a while until my RFEs are implemented (if ever) -- but, one can maintain a wish list. wink

-- RandyKramer - 13 Apr 2002

One good way to get your RFEs implemented is to have a look at PerlTips and start coding smile

-- RichardDonkin - 13 Apr 2002

Thanks for the suggestion, but that may be a while! wink

-- RandyKramer - 13 Apr 2002

I've found myself thinking about this from time to time and would really like to see something like this developed. Not only having a clearly delineated topic summary, but RandyKramer 's idea of continually updated topic "headline" would be a real boost to tracking the evolution of a topic.

I thought of one idea this evening that might work. That would be to have a form field for "Topic summary/headline" or something like that. Then, when each person edited the topic, they would have the option of updating the headline. The next thing I need to figure out on this approach is how to display the form data for this field within the topic (perhaps at the top) and in search results. It appears that one would use the Meta{"form"} variable with a regex to select out just the headline field. Perhaps someone with more technical understanding could comment whether this could work as I envision.

-- LynnwoodBrown - 29 May 2002

Personally, I really like Randy's RFE (2), that is, to show the first 80-162 characters of the last addition to a topic. This is particular useful if one lists the topics in a change log. However, I realize this is tricky. If the change was some correction of an earlier typo, or a formatting change, etc., what do you show? I would be content with scanning the text from the end and finding the first signature that is not the last line of text, and use the first 80-162 characters that follow. While this would not be perfect (e.g., what is when you don't find such signature--use the standard summary; takes much longer than just talking the first 162 characters of a topic; etc.) it would save much time in scanning changed topics.

-- ThomasWeigert - 29 May 2002

I was thinking about the summary for a while. What is we have two variables, SUMMARY and ENDSUMMARY? I set it in my TWiki site, and have demo of it at this page

Do you like it?

-- PeterMasiar - 30 May 2002

Peter - I'm interested in your approach and want to understand it better. How are you using the two variables? How did you use this approach to accomplish the formatting on your sample page? How would you use this to display the topic summary in search?

In the mean time, I'm experimenting with the approach I described above of using a form field for the topic summary/headline. I have edited my basic WebForm to include an 80 character, free-form text "Headline" field. I like this approach because it seems like a natural step of the edit sequence to consider updating this field to reflect whatever is most current in the topic. I just have to figure out how to extract this text from the meta data to display in searches and such.

  • Just an extra note for newbies like myself who didn't know the answer to this last sentence. It's very simple to display a form field in a search result using the $formfield(name) variable in a FormattedSearch. - LB

-- LynnwoodBrown - 30 May 2002

Here is how I created "Executive style" summary using two variables, SUMMARY and ENDSUMMARY, exactly as is done for color fonts:

      * Set SUMMARY = <table align=center width=80% bgcolor="Yellow"><tr><td><b>Summary:</b><br />
         * and all text until =%<nop>ENDSUMMARY%= will be in nice yellow box
      * Set ENDSUMMARY = </td></tr></table>

Then, you type %SUMMARY%Sample page summary%ENDSUMMARY%, and you get:

Summary:
Sample page summary

Then, we can modify search script to detect SUMMARY variable, if close to start of the page, and display summary text until ENDSUMMARY.

Now you have it here, but I wanted you folks to look at this page to see my SimplerDefaultTemplates smile

-- PeterMasiar - 30 May 2002

Actually, had I not been in a rush this morning, I wanted to comment on your SimplerDefaultTemplates! Actually, I think I'll head over to that topic to make my comments where's they are "on-topic."

Any thoughts about the approach I'm pursuing regarding AllowDesignationOfSummary? It's a different direction than you've taken but I'd welcome any comments.

-- LynnwoodBrown - 31 May 2002

Not sure I fully understand both proposals, so I may be making some incorrect assumptions in the following, but (I think) I like a combination of the two ideas:

One -- Main Summary:

I'd like something like the SUMMARY / ENDSUMMARY markers that PeterMasiar describes, but, IIUC, I'd want them to be invisible and not appear as a table. What I'm trying to say is I'd like the summary of a page to be embedded in the body of the text.

For example, if the previous paragraph was the first paragraph of a TWiki page, I'd like to mark it up something like this:

I'd like something like the SUMMARY / ENDSUMMARY markers that PeterMasiar describes, but, IIUC, I'd want them to be invisible and not as a table. What I'm trying to say is <SUMMARY>I'd like the summary of a page to be embedded in the body of the text.<ENDSUMMARY>

In that case, the paragraph would be displayed as the first instance of the paragraph (no visible <SUMMARY> / <ENDSUMMARY> tags), but the page summary would be set as:

I'd like the summary of a page to be embedded in the body of the text.

Of course a shorter markup would be nicer wink -- maybe **{ and **} just to propose something.

Two -- Summary of Most Recent Change:

After seeing the other comments on this page, I agree with what has been implied (or what I inferred) but hasn't quite been explicitly stated -- the summary of the most recent change may be something quite different than the main summary. LynnwoodBrown's 'continually updated topic "headline"' may be closer than "summary", but even closer, I think what I was (am) looking for is a place to provide a short change description related to a revision.

In some cases it would be explicitly describe the subject of the change, like:

  • Added proof of E=MC2
  • Added recipes for Potato Rolls and Bagels

In other cases it would be more of an editorial or summary comment:

  • Fixed typos and "grammos" wink
  • Reformatted entire page
  • Added several examples
  • Added my comments (rhk) throughout document
  • Added my comments (rhk) to PeterMasiar's comments

What I'm trying to say (among other things) is that this type of comment seems less suited to the "summary embedded in text approach" described above, and more suited to the "using a form field for the topic summary/headline" described by LynnwoodBrown.

-- RandyKramer - 31 May 2002

IIUC, we are talking about different kinds of summaries:

  • Executive summary of PeterMasiar, by viariables SUMMARY ...ENDSUMMARY, as used by usability expert Jakob Nielsen's Alertbox, http://www.useit.com, and I definitely want it to be visible near top of the page, but maybe after one or two paragraphs. This is how page get started. LynnwoodBrown prefers a field from TWikiForms here.
  • Invisible summary of RandyKramer (when is visible? For whom?): IMHO special XML tag is better choice:
 
           <SUMMARY> ...text... </SUMMARY> 
  • Summary of this change is nice idea, but not obvious how to handle. Questions off top of my head: Will WebNotify print it in email? Only last one, or all sice last email? Maybe another custom XML flag will be appropriate, like: <CHANGED> ...text... </CHANGED>

-- PeterMasiar - 31 May 2002

This is good! I think we're actually getting somewhere. Thanks Randy for sorting out the threads of the conversation. Thinking about this last night, I had became clear that we were talking about two distinct but similar ideas and you have captured them exactly to my thinking at least. Now reading Peter's comments, I think there is a good case for 3 distinct types of summaries, each suited to particular circumstances and treatments. I.e.:

  • Executive summary giving an overview of the topic. This would be more relevant to topics where the content is less dynamic. Graphically, you want it stand out so Peter's (following Nielsen's) treatment seems quite approapriate.
  • Short "Leadin" summary for intentially tagging a key phrase within the narrative. This would be most relevant where the topic is likely to be included in a list of topics resulting from a search. A good example would be tagging the essential question in a Support request. For these, it seems natural that it not stand out graphically, but be an integral part of the narrative. So having the tags (not the content) be invisible and very simple/short (such as Randy proposes) makes sense. Regarding the search formating, I could see designing a search that checks to see if the tags are present and if not, simply uses the initial n number of characters as in the current convention. This leads me to the question: can we design conditional search strings?
  • Headline for recent contributor to explictly draw attention to, or comment on, what's new. This is clearly more relevent to topics with dynamic content. I say "explicitly" because I don't think "automatic" searches of changed text a la Diffs fulfills the use I see for this kind of summary (and is wrought with problems anyway). Randy's examples reflect very well the kinds of comments I imagine here. The more I think about it, the more I like the headline being in a form field so it's right near the "Preview changes" button. So in the sequence of editing, right as you go to save changes, you see that field as ask oneself: "Do I want to update the headline?" In some cases, I could see displaying this headline near the top of the topic (as PeterThoeny helped me figure out how to do in DisplayFormFieldinTopic).

Reflecting back on this discussion, I started out thinking this would require some code changes but it seems to me now that all that we want to accomplish can be achieved simply with suggested "conventions" such as could be documented in TWikiAdminCookBook. Perhaps the Leadin summary "tags" could be included as one of the default variables.

-- LynnwoodBrown - 31 May 2002

We're having a good discussion here, and I agree / recognize the three types of summary that LynnwoodBrown and PeterMasiar mention.

I'm not sure that all the behavior I'd like to have can be accomplished without programming -- it would be great if it could, but I don't see it right now. Therefore, I will start a list of the things I'd like to have, and if someone can explain how it can be done without programming, that will be great:

  • Tags to delimit a summary within the text of a page, something like <summary> and </summary> or some TWiki markup, like **{ and **}, or both -- I think some programming is required

  • Software changes to pick up that summary and use it in place of the default summary of the first 162 characters of a page -- I think some programming is required

  • "Headline", "Revision Summary", or some other form variable to allow the entry of a short change description for each reference, perhaps defaulting to "not specified" if nothing is entered for a particular revision -- no programming is required

  • Preference variables to specify what changes should be included in the WebNotify email, the WebChanges page, the WebIndex page and similar, and software changes to implement the preferences -- I believe some programming is required for each of these:
    • Show same content as today (but showing "designated summary" in place of default "first 162 character summary")
    • Show same content as today (as above), plus content of "Revision Summary" form variable for most recent change
    • Show same content as today (as above), plus content of "Revision Summary" form variable for all revisions in last 24 hours

  • Whatever it takes to do PeterMasiar's "Executive Summary" (I've not really thought about that very much) -- ??

  • This is almost certainly an incomplete list

-- RandyKramer - 01 Jun 2002

Look at #ExecutiveSummaryImplementation for tip how to create "Executive Summary" using two variables. And of courese summary should be much shorter than current one on the top of the page, max 2 paragraphs. smile And FormattedSearch can be made aware of these vars, and use first 162 chars from "Executive Summary" (if exists), instead of current implementation to use first 162 chars.

It looks for me that "Executive Summary" and "lead-in" designated summary are almost the same thing, implemented differently (new tags for "lead-in", new variables for "executive". Both are better candidates to use in FormattedSearch results than current method (first 162 chars). IMHO both are bad candidates for WebNotify, page title is for that, and they will be just repeated ad nauseam - not a new info => just a noise.

I like idea of special tags, which you can just enter into existing text and selected part will become summary. We can have both, like TOC variable, and selected part of text will be rendered in addition also as yellow table cell on page top, as I proposed. But maybe special tags are too fancy, not-KISS?

Any implementation, if displayed in FormattedSearch, require changes to search script. But variable SUMMARY (as proposed in #ExecutiveSummaryImplementation) is less disruptive: existing FormattedSearch will display plain variable name, but with name being SUMMARY, result will be nice enough, and changes in search script will be nice to have, but not required.

For WebNotify, summary of the last change will be nice enhancement to page title. But it does not make much sense in FormattedSearch: I want to know more what is page about, if it is worth loading and reading. Last change is almost meaningless for search, IMHO.

IMHO we have two different concepts, two topics, and we need two pages, like ShortPageSummary for "Executive Summary" and "lead-in", and RecentChangesSummary for the other one. If somebody agrees with me, edit page name here and create new pages for it.

I also created real short "Executive Summary" on the top of the page, as an example.

-- PeterMasiar - 02 Jun 2002

Two pages would be fine, but I have little impetus to make the change -- I think we've had a good discussion on these topics, but until someone expresses an interest in actually making changes to implement some or all of the ideas, this page seems as good as any to provide a record of the discussion. (Perhaps if someone steps forward willing to be a developer of these changes, they might appreciate something written more in the form of a specification.)

Aside: I corrected a few typos on the page in my own and other's text.

-- RandyKramer - 03 Jun 2002

One thing that has jumped out at me in the recent discussion is that we are walking an edge between technical definition of one or more features and matters of editorial judgement or style. Taking the example of Peter's and my alternative takes on "Executive summaries," we may agree on the basic feature we're looking for (i.e. a way to delineate and display a short summary of topic) and disagree on how to use this feature. All I can say is that given the difficulty I've observed in reaching consensus around technical matters, I'm glad we don't have to reach consensus about these kinds of usage matters. smile

Personally, this discussion has addressed my immediate needs. Contrary to what Peter suggest about headline summary being meaningless for searches, that is precisely what I am going to implement on my site! It will be a WebChanges topic that also displays the topic "headline summary" if there is one. At some point, I would like to be able to include the headline in MailNotify but I don't see this as a high priority for code changes.

Regarding coding of tags to designate summary, I agree that providing some specs might provide encouragement to some coder to take it on. Perhaps we could do that here or in a separate topic. I don't have much experience with that kind of thing but would love to see it and would contribute once I got the form.

Otherwise, I'm ready to let this topic rest a bit before launching into the next round of refactoring and/or splitting off subtopics. Who knows, maybe it's only we 3 who even care about it. wink

-- LynnwoodBrown - 05 Jun 2002

Consider me the Fourth :-).

I have some questions on useability aspects: When we edit the topic, we could provide three edit text box windows: One for summary, One for recent changes, and one for normal topic edit. (And of course, the skin may choose to provide WebForm window as well.) This would be a clutter, but will explicitly draw the attention of the person to edit the changes and/or summary. (This is as opposed to single edit window, and person uses tags to specify the summary/changes.) I feel that useability is better when a separate "changes" window is used.

If we have Summary and Changes as Forms variables (and hence it uses existing Forms edit windows), we can't highlight the changes window.

-- VinodKulkarni - 06 Jun 2002

Just ran across this article by Jakob Nielsen, web usability guru, regarding writing a good page summary, or what he calls "Microcontent" : Microcontent: How to Write Headlines, Page Titles, and Subject Lines. I thought anyone who was reading through this topic might find this article interesting also.

-- LynnwoodBrown - 12 Aug 2002

Referring to the entry PeterMasiar and his #ExecutiveSummaryImplementation on 30 May 2002, i like the idea of the SUMMARY and ENDSUMMARY tags, if people do not want them rendered in normal page display they can set the two variables to HTML start/end comment tags, but the search script would still be able to pick this up and display it in the search results..

As for implementing other forms of summary (change summary/lead in etc as per discussed) there will just become a huge amount of summary information stored in each page, which people will tend not to update as often especially when just adding quick notes to pages, therefore becoming less usefull...

-- JaredQuinn - 12 Sep 2002

While the goal of providing good page summaries is very important, I doubt that the approach would work:

  1. Additional markup violates the KISS principle (You wouldn't use this in simple email text)
  2. Therefore, many people won't understand it
  3. Therefere, even more people won't use it
  4. Therefore, overall quality will decrease

I propose to concentrate on improving the current way, i.e. show the beginning of the page:

  1. change the edit templates: put in a line at the very beginning like
    [state the abstract or goal of this page here]
    Actually, stating the goal like this is useful anyway; for the writing process, for the structure of the page.
  2. Strip off markup garbage like %INCLUDE stuff
  3. The 162 characters rule seems to rigid. How about "the first paragraph"? Once, I implemented this for a TicketWiki and found it very useful. Most summaries would become a bit shorter, some longer; possibly cut them at ~ 2 × 162
  4. Do not clutter the summary with extra headlines, which simply restate the title: see SimplerDefaultTemplates - make the topic name stand out more clearly. Refraining from redundant headlines also facilitates a better IncludeStrategy.
  5. Possibly make that first paragraph stand out visually by separating %TEXT% + %SUMMARY% to be re-assembled in template?

The question of change summaries has been discussed in

  1. DiffsHardToRecognize
  2. AddCheckInComment

-- PeterKlausner - 12 Sep 2002

The discussion in FormattedSearch reminded me of the patch, which implements the above mentioned strategy. Note, that it won't buy you much, if sloppy/redundant entry paragraphs are as frequent as in Codev. But then, what does? At least, the added control is an incentive to write up a good lead-in paragraph.

-- PeterKlausner - 12 Sep 2002

All of the requests in this topic can be achieved through NamedIncludeSections. After all you would define a section "summary", "headline", etc, and then pull in as you want - as well as mesh cleanly with the sectional edit plugin/etc. Logically you also have "last addition", as well as the various auto-generated section links (by TOC) and so on. Combine that with a skinned bookview and you can view all changes to all pages along with headline & summary in a single page view.

I've actively wanted to have named sections for quite a while - for various reasons, and now have the (home) time to implement this. Ideas on syntax/notes from other people as to what they'd like from it are welcome.

-- MichaelSparks - 12 Jun 2003

Just a note to say that a patch for NamedIncludeSections now exists, and is attached to that page. I've summarised the two patches available for this topic at the top of this page.

-- MichaelSparks - 14 Jun 2003

I don't really which approach will be taken. But having rows and rows of summaries which read like

Related topics: SEARCH{"WYSIWYEditors" scope "text" regex "off" nosearch "on" nototal "off" order "modified" reverse "off" format " $web.$topic $topic , " web "Co
clearly does no good... I don't now how my patch fares with this %gooble%di%gook%, but it can't get any worse, does it?

-- PeterKlausner - 23 Aug 2003

It can get worse. The syntax PeterThoeny advocates for NamedIncludeSections (when he removed a better/more standard quoting style from the patch) results in a search for summaries looking like the abortionate markup below:

%SEARCH{ "[S]ECTION{.*title;" limit="10" scope="text"  reverse="on"
order="modified" nosearch="on" regex="on" nototal="on"
format="---++[[$topic][$percntINCLUDE{$quot$topic$quot
section=$quottitle$quot}$percnt ]]$n<font
size=-1>[[$percntSCRIPTURL$percnt/edit/$percntWEB$percnt/$topic][edit]]<br>
$n$percntINCLUDE{$quot$topic$quot section=$quotsynopsis$quot}$percnt"}%

Which is partly why I prefer the approach I outlined in LogicallyNestedWebs - which I haven't implemented yet, but is IMO clearly more userfriendly. Combining that with parameterised named include sections (the latter simple enough to do in practice) and you probably get something cleaner for end users, than the above rather disgusting markup. Mind you, you need IncludesAsProperlyNestedRequests for that to work correctly - as do lots of other features.

However, with stuff like the above it makes more sense to do a SSI for an SQL command against a database, results formatted as XML, with an XSL style sheet applied automatically - it'd look a damnsite clearer and have much better separation of presentation from logic.)

I suppose the biggest problem here is that many people still haven't figured out that TWiki forms a database, and are still thinking in terms of pages/topics rather than rows/tuples. (There are some very notable exceptions of course, including one very outstanding piece of work smile )

-- MichaelSparks - 24 Aug 2003

Strong language and insults do little to move forward Codev. It must also be remembered that there are valid alternatives points of view. For instance:

Pro-database:

  • Clearly more appropriate for much of TWiki data e.g. meta data and permissions.
  • Gives many useful facilities, especially for data organisation and searching

Against-database:

  • Adds to instalation difficulty of TWiki
  • Not a natural for text (see the hoops documentation systems like Documentum jump through)

-- JohnTalintyre - 24 Aug 2003

In case you're referring to my comment - you think that was insulting? To who? That quote was directly out of a page I've created using functionality I've created using a syntax compatible with that which the CoreTeam want. I describe it as "abortive" because that's precisely how I view it - pretty disgusting to look at and pretty disgusting to write. It's an honest opinion regarding useful functionality.

If I was attacking anyone, I was attacking myself - the example, functionality & syntax are straight out of stuff I have created - am I not allowed to be self-critical? I was pointing out that in terms of "friendliness" it makes more sense to take a different route. If I really thought that was the best route overall I wouldn't be using (and developing for/on, and submitting patches for) TWiki.

For example, using a database makes one key aspect of TWiki more difficult - version histories and auditting. It can be done, but doing it as well is difficult. However my point was that some TWiki idioms do not extend, and when stretched, extend very, very poorly - in a way that makes their creator revolt when seeing them. The fact that Peter chose to enforce the above version rather than the less abortionate one isn't my problem - I personally find the combination of syntax abortionate - and that's my honest opinion.

Or is honest and frank feedback frowned upon here? Most open source projects encourage honesty - rather than constantly asking people who contribute time, energy & code to toe a party line.

-- MichaelSparks - 24 Aug 2003

It's easy to forget how easy it is to mis-interpret emails and Wiki content. Words and phrases like: abortionate, disgusting and many people still haven't figured out may be just intended to make a point, but IMO it is more effective to make concise arguments worded in ways that are not so likely to alienate people.

-- JohnTalintyre - 25 Aug 2003

Category: TWikiPatches


I don't think a new summary tag needs to be invented. I also don't think we need to pull in a heavyweight like NamedIncludeSections or start creating new variables. There is a perfectly good construct available, the definition:

AllowDesignationOfSummary_ExecutiveSummary: towards a more usable page summary, and the realisation there are several different kinds of summaries even though we often use the same words to describe all of them.

...which could be used by formatted searches, e.g. like CairoReleaseSummary. (it would be good to fix the twiki definition markup to be able to use bold etc. Implemented! Feb2004)

...while the first paragraph would work dandily for the "this page is about" kind of summary. Especially if it was highlighted by emphasis or perhaps within a |one cell table|. Extending the 162 character limit to to the end of the first paragraph would make the WebIndex and similar more useful.

-- MattWilkie - 20 Jan 2004

Agreed named include sections isn't necessary to implement this, it's just another method. (Though the current version does have the ability to make values HTML tag attribute safe. (Nice for having a list like CairoRelease with the features summaries available as popup/mouseovers using the title= attribute.)

The approach of using a topic summary field as below, in conjunction with using forms for settings (along with the minor restriction I suggested lifted) allows for insertion of the summary and other niceness at the top of a page using a preamble like:

---+ %TopicStatus% : Some Title text
%TOC%
%TopicSummary%

Whilst nice, though it's not very wiki. A much nicer solution than I've seen to date is used by FlexWiki.

-- MS - 03 Feb 2004


thanks for the updated patch PeterKlausner. smile

-- MattWilkie - 04 Jun 2004

Please forgive me for only searching not reading this whole topic before adding this comment: (I read the summary then searched for meta).

Surely summaries are meta-data? If so, it should be a trivial matter to extract the summary as a form-field.

Furthermore, a form-field could also be introduced in a BeforeSaveHandler to replace the lastDiff meta-data field with a diff; that diff could be easily extracted as above.

-- MartinCleaver - 28 Sep 2004

BasicForm
TopicClassification BrainstormingIdea
TopicSummary towards a more usable page summary, and the realisation there are several different kinds of summaries even though we often use the same words to describe all of them.
InterestedParties

RelatedTopics

Topic attachments
I Attachment History Action Size Date Who Comment
Unknown file formatpatch paragraph_summary.beijing.patch r1 manage 1.3 K 2003-09-16 - 20:08 MattWilkie Patch BeijingRelease makeTopicSummary = 1st para
Unknown file formatpatch paragraph_summary.cairo.patch r1 manage 1.1 K 2004-06-03 - 21:06 PeterKlausner Patch CairoRelease, assuming it will resemble TWikiBetaRelease2004x05x07
Unknown file formatpatch paragraph_summary.patch r1 manage 1.2 K 2003-06-12 - 07:23 PeterKlausner Patch AthensRelease makeTopicSummary = 1st para
Edit | Attach | Watch | Print version | History: r47 < r46 < r45 < r44 < r43 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r47 - 2008-09-02 - TWikiJanitor
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.