Comments:User Guide

Intro

Hi Matthias (x28): I see you're already improving this page right after my creation. That's great! What do you think about the chapter/section layout? I tried to respect your note (on the mailing list) about the 4 usage levels.

Are you in the mood of migrating some content of the "How To" page to this "User Guide" and then strip it from the "How To" page? The aim is to create the canonical DeepaMehta "User Guide" here and have the "How To" page for the more exotic applications and modalities found by the users.

Jörg Richter 12-May-2008 16:58 CEST

Terminology problem

x28de 13-May-2008 19:45 CEST Ok, trying to move some HowTo's to the User's Guide. First part: Retrieving Content. I hesitated to use this title that suggests DeepaMehta was a mere Storage & Retrieval Tool and which reminds one to dry librarian applications or to Knowledge Management 1.0 which was focussed on capturing, storing, and retrieving "knowlegde" = facts = information. So I provisionally sticked to the previous title, "Unhide" topics.

You renamed the section from Retrieving Content to Un-hide topics. I see your point but don't think your title is a good choice. I think un-hide is not an english word, and not understandable. Furthermore, with DeepaMehta there are not just topics 'un-hidden', but also associations.

My suggestion: name the section Revealing Information or Revealing Content. I would prefer the latter because it is conform to the other section titles.

Terminology issue: I suggest to clearly separateinformation from knowledge. I'm deeply convinced, and the DeepaMehta design deeply embodies this conviction, that knowledge is never stored in a machine, but exists exclusively in heads. Machines stores information. The process of creating knowledge from information -- learning -- belongs to the realm of humans. It is an individual process, performed by humans in a situated context. So, I would not write "retrieve content, i. e., get knowledge" to explain a software function.

--Jörg Richter 18-May-2008 14:42 CEST

• x28de 19-May-2008 00:16 CEST Thanks for the thoughtful consideration. i am going to change the current title (which was not mine, BTW) to "Revealing Content". Although I also have my problems with "Content" (see below), the main goal here is understandability, and if "revealing topics" is wrong and "revealing topics and associations" is too long, I can live with this until we find a better distinction. At least, "retrieving" is off the table.

As always when doing end user descriptions, one stumbles upon terminology questions. I personally think that the term "corporate memory" should gradually disappear from the user surface (of course in the code it may stay). In recent web 2.0 developments, "corporate" is more of a provokative, emotive word that often denotes right the opposite of democratized peer work and social knowledge work. Perhaps it was meant more in the sense of the entire organization where "enterprise" is more usual than "corporation", but we could ask the native speakers.

I agree with you: comprehensible documentation needs concise terminology. Although the concept of the Corporate Memory doesn't appear in the DeepaMehta user interface, it is still part of the user's mindset. In order to exploit the power of DeepaMehta the user must know the concept of the Corporate Memory and that's why it is explained in the user guide.

However, I accept your invitation to rethink the term "Corporate Memory" itself. I see the term not only rooted in the world of business ("company"/"corporation"/"enterprise"), and would like if it is readable also as "Gesamtgedächtnis"/"Gemeinsames Gedächtnis". Yes, it is a good idea to ask a native speaker about that.

Thank you for the hint, the term "corporate" might evoke misleading associations. Although I see no priority for changing the term Corporate Memory I'm curious about more adequate terms.

--Jörg Richter 18-May-2008 15:42 CEST

x28de 13-May-2008 23:50 CEST "left side always shows a topic map" is not entirely true. It may also show

• personal workspace (person-icon) or
• the shared workspaces (group of persons-icon),
• an error or information message,
• or a maximized "What is" window.

Also for beginners, it is rather "the" topic map than "a" topic map. By contrast, the right side contains the details for one of many topics or associations.

Layout and Images

nice to read already. i try to stick to our progress ;) before i want to resize some pictures to a smaller size, like in other wiki sites (fullclick for full picutre), it would be good to clarify the layout dimensions of the articles and my suggestions therefore would be, either 1024 or 1280 pixels of width and with pictures that big, that the content is flowing around. just formal stuff... should we fix the resolution absolute?

I'm very fine with the current images (which are sized carefully). Furthermore, in the context of the user guide, where most images are screenshots, I see no advantage of "thumbnailed" images (extra click to see full size), but a disadvantage when it comes to handling (text and image are not "readable" together) and printing.

The original layout concept of the user guide:

• The page must looking good at 1024 pixel screen width in order to "work" also on beamers
• There is no fixed page size
• Screenshots of the whole DeepaMehta window have a width of 700 pixel and are not floated by text
• Partial screenshots for displaying e.g. menus have a width of about 300 pixel and are floated by text
• Screenshots may be scaled down, as long as readability is not compromised
• All screenshots are the real thing, no thumbnailed previews
  • I think exceptions should be possible, for screenshots showing ample "big picture" maps. x28de 19-May-2008 20:36 CEST
• Screenshots should have a caption which at least explains what is seen on the image

In my opinion the highest priority at the moment is to fill the missing parts of the user guide. I think what potential DeepaMehta users need most is a comprehensive user guide. I feel we accomplish that aim best, if we do the hard work of content creation first and then focusing on revision and style.

--Jörg Richter 19-May-2008 13:28 CEST

Malte 19-May-2008 15:46 CEST Thanks for explaining this layout strategy in detail, i agree on the most steps with your suggestions and i am willing to stick to these and revert some changes according to this. I just want to comment: to discuss these things in an early stage of development, in my opinion, is very important to not double our working time. now we can communicate about this layout and introduce it to new authors and contributors in this wiki as well.

i removed some handling explanations out of the screen layout section in thinking of clarifying and minimizing, do you think the interface overview may contain additional handling information. this could be also served within the Quickstarts or in a subsection below.. we`ll see? perhaps i am wrong on this. Malte 14-May-2008 01:52 CEST

x28de 19-May-2008 20:36 CEST I put in a modified version of the first screenshot:

• Removed the associations extending over the right border and the grey arrow, which interfere with the understanding of the relationship between the selected topic and the property pane: all three incidentally pointed to the propery pane;
• Inflated the red rectangle around the selected topic for more clarity. This is an unusual concession. Normally, screenshots can be annotated by a very flashy color. In the ergonomically optimized UI here, this red markation is already taken. So I thought that inflating it a little, would yield most clarity for this important concept, the relationship between selected topic and the right pane. Ideally, a hovering double-headed arrow would further emphasize the relationship, but this is probably not possible in the wiki. We should consider, however, to highlight it in the image caption text.
• Replaced the old Logo at the right by the current logo at the left.

(The previous image artfacts-12142506.png is still available).

Organisation of first sections

x28de 14-May-2008 19:48 CEST Thanks for correcting original English of the left/ right sides, bur I moved them to the start of the header again because the reader expects: what is on the left, not: where is this or that. Continuing the Guided Tour through the interface, I adjusted some more headings. "Context Menu" is something very remote from the user, I prefer "right-click".

After I changed the heading from "Topic Map Context Menu" to "Right-click...", I noticed that the section did not focus on the Context Menu = Right-Click but on the Left-Click.

Frankly spoken, I was quite upset at first to see chapter 1 "Interface Overview" completely rearranged. Now I see this as a chance, and at the same time the need, to communicate the concept of my original chapter layout.

Chapter 1 "Interface Overview" is supposed to explain the DeepaMehta user interface at a conceptual level. The interface elements are identified and named and their function is explained roughly. Proper naming is crucial for reference purposes (see e.g. section "Create a Topic Map"). The subheaders of section 1.2 "Interface Elements" are meant to be the names of interface elements: substantives.

Chapters 2 to 6 are supposed to explain DeepaMehta at a task-oriented level. Most of the section/subsection headers are describing tasks: a phrase containing a verb.

After your rearrangement the advantage of named interface elements is gone. Your sections are titled now according to operations, e.g. "Right-Click a Topic" and are assembled under the header "What you can do". In my opinion you confuse What with How here. Clicking a topic is not what I'm doing but how I'm performing a certain task. What task? That's what chapters 2 to 6 are about.

Dear x28de: despite my critique I see your changes are thought-out. I appreciate your systematic thinking and your mature writing stlye. Due to your engagement the long-awaited DeepaMehta user guide is eventually growing. This makes me very happy because I think what potential DeepaMehta users need most at the moment is a comprehensive user guide.

--Jörg Richter 19-May-2008 01:46 CEST

• x28de 19-May-2008 18:59 CEST Many years ago, a typical IBM product documentation set consisted of a User's Guide, a User's Reference (and a Diagnosis Guide, a Diagnosis Reference, a "Messages and Codes", a Programmer's Guide, a Programmer's Reference and others that I don't recall off-hand). When I saw the Guide's drafts I noticed that it looked much like a Reference, and I wondered if we would need both.

Reference books have become more unfrequent, probably due to the context specific help, and due to the fact that people don't RTFM anyway. So I cautiously tried to resolve inconsistencies towards the Guide direction, e.g. the issue (described previously) of "Context Menu" vs. right-click plus left-clicks, or the dilemma that an "Overview" from the User's point of view is what s/he sees (left/ right pane) while from the conceptional POV it may be different. I was aware that the resulting text was still a compromise between Reference (How) and Guide (What).

If we do need a document of the Reference genre, we definitely need also a separate Guide, and then we should best discuss also the roles of pages like Quickstart, Tutorials, FAQ, HowTo. But I think that the chronological priority should be from the most compact to the more detailed, i. e., Guide before FAQ/ Reference/ HowTo, and Quickstart and Tutorial even before Guide.

And thanks for the acknowledgement and also for the open words.

User Problems Noticed while Writng

Trying to think about the order of basic operations, I noticed that there is an unneccessary little usability problem with the program startup: why doesn't it start with the personal workspace bur with a "map" that does not allow the promised right-click? So, some steps need to be prescribed that should be explained much later: how to jump. Otherwise, one could recommend to create (better import) a map and just double-click it.

And another terminology problem: why call this border case "topic map" a topic map, although it is different from what the topic map selector description shows as "topic map"? I think, programmers' generalizations may be an elegant way to harmonize behavior (including some user controls) but it harms the learning curve.

• For e.g. in my opinion the name Topic Map Selector, could be named to "Context Selector" or clearer "Working-Context Selector", because that is what you mostly do as a user in DeepaMehta terms if you select another topic map: you are switching your working-context, either to select a personal map of interest or a shared map of interests. Another suggestion of mine would be something like: in your "Personal Selector" (like in Personal Computer) Malte 19-May-2008 17:57 CEST

Similarly, the generic topic should perhaps not be called topic.

Even more severe is my terminology problem with "content". I think, the relative proximity of topics, in context to each other, and the construction of a revealed subset of topics, is definitely content in the sense of: product of potentially many hours of thinking process, or even more important, an unfinished stage in this thinking process that should under no circumstances be lost. This is a fundamental difference of focus, whether you have a bias on the verbal and relational content or on the visual content, and whether the bias is on the long-term stored data/ facts/ information, or on the temporary extension of brain's working memory where new knowledge emerges, and which one you prefer to call knowledge, at all. But, after all, both of these views refer to affordances of DeepaMehta, and so, mere terminology should not hinder either of them.

I would suggest that, in critical passages, "content" should be replaced by "stored contents", and be distinguished from "visual content". Or storable or unhideable vs. exportable or map configuration content? I would be glad if someone found better names.

Chapter 3 and 4

x28de 02-Jun-2008 20:31 CEST, Chapter 3. I couldn't manage to define working properties in my tests, so I descibed the simpler approach to derive a subtopic from an existing one. I couldn't say anything about the association types and their affiliation to the three out-of-the-box workspaces. Sorry that I cannot help with excactly the sections that are most urgently needed.

• Malte i will try to fill the gap whereever it is possible, properties as a composition associated to a type, doesn`t work? maybe you forgot the "update" command?
  • x28de Yes, exactly, I didn't think of the update command although I described it myself elsewhere.
  • Perhaps we should provide a section like "What about saving" for the user who is used to traditional saving, describing that there are various similar concepts here, such as
    • update,
    • "click something on the left side" (your note in "Filling in content"),
    • Click enter after naming a new topic,
    • Close/ reopen maps for completing the delete operations in other maps

Similarly, I could not, just from the user interface, guess how to do simple collaboration (or privacy, for that matter). Perhaps my text fragment may serve as a prompting cue for those initiated or familiar with the code to fill the deep gaps. But please don't hestiate to change these texts of mine as you see fit.

x28de 08-Jun-2008 00:06 CEST After Malte's explanations in Type Descriptions I dared to write down what I understood the collaboration functions. Please check it 'cause it may be awfully wrong!

"Setting Types into Relation"

Thank you for the explanation of the "Relation" association type. Your examplary "tagging" scenario is chosen well. All information is correct and you keep track properly. The screenshot is arranged well.

With further improvement in mind I like to tell you 6 considerations. Some are related to the section "Setting Types into Relation" in particular, others are related to the user guide as a whole.

• "Meta Topicmaps" is not a DeepaMehta concept. Therefore this term should not be used. DeepaMehta deliberately makes no separation between content topicmaps and structural (or meta) (or model) topicmaps. It is possible to work on content and structure at the same time, within the same map. Nevertheless, sometimes it might reasonable work practice to have a separate topicmap for model and content. I feel work practice should be separated from the canonical user guide information. Perhaps it is a good idea to have a separate chapter dedictaed to DeepaMehta work practice.
• Separation of what and how. It might be a good idea to introduce every list of action-items ("right-click this ..., point to that...") with an exact description of what task is actually performed there. The introductions for your first two action-lists might be:

1. Create a "Tag" topic type
2. Reveal the "Topic" topic type
3. Create a relation between "Topic" and "Tag"

(please note: your second action-list is splitted here into two separate tasks)

This separation of what and how might provide three advantages:

• The intoduction would focus on what task to perform, and the action-list would tell then the details about how to do it. A user who already read about the basic operations (chapter 2) could possibly skip the detail list, because he already knows how to reveal a certain topic. The user would perform faster and gain success earlier. (If the chapter about basic operations is well written, the detailed action-lists could even be stripped because they would contain a lot of redundant information and clutter the user guide.)
• The relationship between the overall task and the sub-tasks is made more clear and better memorable. (Look at the 1. 2. 3. list above: it provides the pure essence about what you're actually doing and what to keep in mind.)
• It could be easier for the reader to recognize the underlying principle and to transfer this example to other situations.

• Section introduction. It could be a good idea to introduce every section with an introduction to answer the reader's basic questions:

• Why/when should I use this feature? In which a real-world situation is the use indicated?
• What problem does the feature solve? How does the solution look like?
• What is the basic mode of operation? What entities are engaged and how do they interrelate?

• DeepaMehta mode of operation: the defined relations are derived to all subtypes. That is, for the tagging scenario all topics can be tagged now, not only the generic ones (because virtually all types are derived from the base type "Topic").
• Further screenshot. To illustrate the final result a screenshot displaying the "Assign tag" command would be very appropriate.
• Scaled down screenshots. To avoid the screenshot be taken for the real interface it might be a good idea to scale down the screenshot. The other screenshots in this guide are scaled down to 80% (as far as I remember).

--Jörg Richter 12-Jun-2008 18:14 CEST

x28de 13-Jun-2008 01:21 CEST OK, I tried to implement the suggestions. Furthermore, I have now definitely reached the last section where I could help; anything else is for insiders.

x28de 14-Jun-2008 01:17 CEST So, all non-desktop sections are at least filled.

Intended Changes

• Malte seeming so, that my approaches to modify sentences is not in the sense of the new wikiquette, but i want to show up my intentions for changing the content i had changed:
  • x28de 05-Jun-2008 19:35 CEST Your changes of my text snippet contributions are OK.
• User Guide#Create an Association. The 3 button mouse hint is platform independent feature and not a specific linux/kde feature. -> suggestion moving this o for forne line higher

About 5.6.1 Incorporating Documents

(May be named to Document Management and should adress all topics regarding documents under deepamehta contorl, but i like the easy start of his paragraph with the input-output metaphor) Intended Change is:

"To get them in, ideally you can accomplish this by simply drag and drop them onto the pane but this works currently just for Mac and Windows Users. Linux Users have to make use of the create command to create a new document topic in which property panel will be the option for choosing a file from your storage." (Is the create command described in earlier chapters as the canonical way to create something new within a map? just thinking about consistence terminology) "

About 2.1.3 Fill in Content in the Property Panel

Entering longer texts into description fields, or entering search strings into the search field, toggling radio buttons, or copying and pasting HTML contents - all is done that way. Images are put into the property panel by drag and drop into a Property like 'Description', of Visualization Type 'Text Editor'. However there are some limitations. In any case, dropping images only works when dragged from the web browser. Dropping image files (e.g. from windows explorer) to the property panel doesn't work yet. You might not be able to export a topic map to PDF if topics contain images.

About 4. Working Collaboratively I would like to move the first paragraphs in brackets since they represent not a good practice and also need administrative privileges to clean the personal workspace maps out of a users view. But i agree, that this current status at least should be documented but just not in the first lines of this chapter ;) i would like to shorten this text and move it more downwards in this chapter. it could be either filed under a section, what have i done? or something like while practicing and exploring something happened which is not straight forward to me what do you think? Regards --Malte 04-Nov-2008 20:37 GMT

Associations

(Malte cont'd:) I think there are simple answers for association types, which are for the deepamehta core and all of them can be used by the humans for every topic type they want to use it for. The interpretation of the association types in the deepamehta standard workspace is independent from their usage in other workspaces, as far as i know and those associations which control the inner functions of deepamehta are not deletable for a normal user. still the question arises, wherefore are they existing? imo: out of a user perspective, this thirst for knowledge should be appeased in an advanced documentation page but we can provide simple answers here which are not implicit wrong. An aggregation for example can be interconnect any topics you want, if you want to represent that those two needs each other somehow. imo: we should not try to leave the user alone with open questions about the usage here, if the user cannot do anything wrong it is ok if he doesn`t understand the inner functions of the resp. associations, because he don`t need to.

• x28de OK I gave up trying to understand which association belongs to which of the three workspaces or what they do for the core, and I simply merged them alphabetically with the topic types. But for the end user, Malte is right that there should be answers. I once put a question here in my feature request (while proposing to hide all the core stuff):

"Furthermore, even when customizing one's own types, they cause confusion about whether such a built-in association is also appropriate for normal content, e. g., if a simple hyperonomy or partonymy may be (or must not be ?) modelled as a derivation or aggregation or composition"

(The user probably hopes that using the correct types will save him work, by inheriting useful behaviors).

Going on

x28de 14-Jun-2008 15:05 CEST I started with the Desktop chapter to accelerate the completion of the User Guide. I hope I was not too abstract and general because I have practically no experience with document types (I keep getting an error saying "no application assigned to the mime-type" no matter how I assign the two). So I wrote some more general considerations, and I am not angry if this is not wanted here and if it is swapped to somewhere else outside this guide.

x28de 14-Jun-2008 20:10 CEST Regarding MIME types, I finally managed to guess how it works and could open a .txt file. But with images I get silly error messages from my Vista: I created a document specifying the original file location (outside DeepaMehta). When I doubleclick the document topic, the file is found and copied to install\client\documents but this very name is quoted in an error message from Paint saying Paint could not find this very file. Perhaps the path name is in UTF-8 rather than ISO8859-1 ? More mysteries.

I think now that the insiders can fill my gaps and correct my misconceptions easier than writing text from scratch. If not please wave. BTW I forgot to login, 14-Jun-2008 19:35 84.173.126.171 ws me.

• Malte 17-Jun-2008 13:09 CEST you are right, for me at least it is much easier to build upon your texts, than starting with some from scratch also cause i don`t have that much time these days, i am looking forward to go through all of your chapters slowly and one by one, you did very much! thanks!

x28de 15-Jun-2008 12:31 CEST I included some sentences in the User Guide that eventually fit better in other documentation types, such as sales pitch, or hints about quirks that the user might notice but not understand. The priority was breadth before depth. Balancing the various Guides, References, Demos, Tutorials, Screencasts, and "Sales Pitch" blog posts and the like, can take place after the User Guide was covered. Also for some quirky limitations, it may be easier to polish the code than to polish the documentation. Hope nobody is angry.

Changes to chapter 3

--ziegi 29-Jul-2008 13:37 CEST

• I just added a note that it is not possible to subtype the Type Builder types.
• Regarding http://deepamehta.newthinking.net/wiki/en/User_Guide#Configure_the_Search-_and_Create-Menus I experianced that changing the ordinal number of the Type Access in the workspace did not help. But changing the the ordinal number of the Type Access related to my own user did do the job.