Home » Developing U++ » U++ Developers corner » Documentation and Topic++
| Documentation and Topic++ [message #12713] |
Tue, 13 November 2007 19:41  |
 |
mirek
Messages: 14290
Registered: November 2005
|
Ultimate Member |
|
|
| Mindtraveller wrote on Tue, 13 November 2007 08:33 |
OK. I started making new articles.
For now, two things impedes the most:
1) Unnatural division of package docs by "src" and "srcdoc". After some learning it seems like one stands for index while other stands for manual.
I would refuse such a division because index must be one for all packages (smth. like MSDN where I type first letters and got functions starting with them). So all we need in the package docs tree is articles (I would refuse treeview of structure too - as described in forum messages).
|
Well, first of all, the idea behind Topic++ is that it should serve as tool for documenting both the program structure (sources), but also the application being developed (help, application manual).
That is the original idea behind documentation groups.
Now "predefined" groups are
src - this should contain a straight *reference* to the code *interface*. Note that theide is able to bind documents to the code. We have big plans on improving on this. (think "reference" part of MSDN API documents).
srcdoc - this should be for other programming documents - guides, explanations etc...
srcimp - this is intended to contain the comments about code implementation.
app - application documents - help, manuals etc...
| Quote: |
2) Inexistence of first common page. I think there must be root page, and this page must be default (but when we click some package` article, it shows in help window).
For now this root article is finished and I started writing inner articles, which were linked from root.
|
"index" page is considered "first common". Obviously, there is a little problem as this really works well only for single group in single package...
Mirek
|
|
|
|
| Re: Documentation and Topic++ [message #12720 is a reply to message #12713] |
Wed, 14 November 2007 04:32  |
Mindtraveller
Messages: 917
Registered: August 2007
Location: Russia, Moscow rgn.
|
Experienced Contributor |
|
|
I think this is of course great to have one help engine for development docs and user (not programmer) documentation on application developed. So I vote for the original idea.
Next, from the design point of view, treeview-control guiding system as well as "predefined groups" seems to me not very optimal.
I`ll try to make suggestions how to increase usability. Of course, everything below is my point of view and a subject for discussion:
1) Leving behind any "magical words" line "srcdocs","srcimp". We simply don`t need that kind of magic. We need simple things to concentrate attention to the help text itself - without user`s brain guiding through magical labyrinths.
2) Information on package must be concentrated in one articles-tree. Each article has index-tags. So user has 3 ways to look at docs: manual view mode, index and full-text-search modes. Last two modes I`d like to be as MSDN ones.
This approach seems to me little more general. General enough to handle with programmers` manual as easy as user help.
3) src* groups are presented as:
src - number of articles, generated by TheIDE (and linked from some other articles if necessary). I`d prefer some package article to have these links listed by logical or functional groups (alphabetic access is available through Index mode).
srcimp and srcdoc articles are represented as links from (or part of) articles about respective subjects.
The general approach is the same: different kinds of information about subject must be in easy reach from parent article about subject. It seems very obvious way of making things user-oriented.
4) Fimally, general view of help system with approach suggested will be something like this:
5) Thoughts about root article I`ll try to write later, as all ideas about it come in order.
[Updated on: Wed, 14 November 2007 04:35] Report message to a moderator |
|
|
|
| Re: Documentation and Topic++ [message #12724 is a reply to message #12720] |
Wed, 14 November 2007 11:46 |
|
mirek
Messages: 14290
Registered: November 2005
|
Ultimate Member |
|
|
| Mindtraveller wrote on Tue, 13 November 2007 22:32 |
I think this is of course great to have one help engine for development docs and user (not programmer) documentation on application developed. So I vote for the original idea.
Next, from the design point of view, treeview-control guiding system as well as "predefined groups" seems to me not very optimal.
|
Yep, I agree. The help page definitely needsd an improvement.
| Quote: |
I`ll try to make suggestions how to increase usability. Of course, everything below is my point of view and a subject for discussion:
1) Leving behind any "magical words" line "srcdocs","srcimp". We simply don`t need that kind of magic. We need simple things to concentrate attention to the help text itself - without user`s brain guiding through magical labyrinths.
|
Mostly agree, but I think medium advanced user will need to know those magic words too, so that he can use Topic++ to write docs...
Considering other points, the only thing I would like to add is the vision that the future ide will provide much better code/documentation integration.
One of ideas is that browsing the .h file, you will have small icons in left bar (when breakpoints usually are) for each code element (e.g. method declaration); moving the mouse over that icon will popup documentation for the item.
If documentation is not available for item, icon will look differently and clicking it will move you to topic++, generating the text template to document the method.
Similar capabilities should be available in new class browser too.
In .cpp, the idea is that instead of "src", these will lead to "srcimp".
Mirek
|
|
|
|
| Re: Documentation and Topic++ [message #12727 is a reply to message #12724] |
Wed, 14 November 2007 13:24 |
Mindtraveller
Messages: 917
Registered: August 2007
Location: Russia, Moscow rgn.
|
Experienced Contributor |
|
|
| Quote: |
Mostly agree, but I think medium advanced user will need to know those magic words too, so that he can use Topic++ to write docs...
One of ideas is that browsing the .h file, you will have small icons in left bar (when breakpoints usually are) for each code element (e.g. method declaration); moving the mouse over that icon will popup documentation for the item.
If documentation is not available for item, icon will look differently and clicking it will move you to topic++, generating the text template to document the method.
Similar capabilities should be available in new class browser too.
In .cpp, the idea is that instead of "src", these will lead to "srcimp".
|
Could you please describe why exactly is it needed to use these words? I think it is way too hard for understanding "by default". Yes, user may learn manual on that subject, but what for?
It`s nothing prevents us from adding these comments simply by clicking left icon and typing docs in the same window, without any additional identifiers. For me it is so natural, that I have to think of arguments to make this thought clear.
[Updated on: Wed, 14 November 2007 13:33] Report message to a moderator |
|
|
|
| Re: Documentation and Topic++ [message #12728 is a reply to message #12727] |
Wed, 14 November 2007 13:41 |
|
mirek
Messages: 14290
Registered: November 2005
|
Ultimate Member |
|
|
| Mindtraveller wrote on Wed, 14 November 2007 07:24 |
| Quote: |
Mostly agree, but I think medium advanced user will need to know those magic words too, so that he can use Topic++ to write docs...
One of ideas is that browsing the .h file, you will have small icons in left bar (when breakpoints usually are) for each code element (e.g. method declaration); moving the mouse over that icon will popup documentation for the item.
If documentation is not available for item, icon will look differently and clicking it will move you to topic++, generating the text template to document the method.
Similar capabilities should be available in new class browser too.
In .cpp, the idea is that instead of "src", these will lead to "srcimp".
|
Could you please describe why exactly is it needed to use these words? I think it is way too hard for understanding "by default". Yes, user may learn manual on that subject, but what for?
It`s nothing prevents us from adding these comments simply by clicking left icon and typing docs in the same window, without any additional identifiers. For me it is so natural, that I have to think of arguments to make this thought clear.
|
Well, if nothing else, groups are important if you are importing Topic++ into your code - you do so by package-group quantities.
So perhaps for documenting the code, you could do without it, but for using Topic++ as application document resources, understanding of groups is unavoidable.
Mirek
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Re: Documentation and Topic++ [message #13025 is a reply to message #12713] |
Wed, 05 December 2007 18:19 |
Mindtraveller
Messages: 917
Registered: August 2007
Location: Russia, Moscow rgn.
|
Experienced Contributor |
|
|
Ok.
I suggest having 2 types of docs: autogenerated from sources and manual. Manual articles may hypelink to source-autogenerated articles. All these docs are accessible by 3 tabs:
1. Index
indexed source-autogenerated articles;
2. Manual
manual docs, something like site with hyperlinks;
3. Search
full-text search within source and manual docs;
user may check areas for search: source, manual, or both.
Only tabs, no magic words. Plain and simple.
Is it OK, any corrections?
[Updated on: Wed, 05 December 2007 18:19] Report message to a moderator |
|
|
|
| Re: Documentation and Topic++ [message #13027 is a reply to message #13025] |
Wed, 05 December 2007 19:18 |
|
mirek
Messages: 14290
Registered: November 2005
|
Ultimate Member |
|
|
| Mindtraveller wrote on Wed, 05 December 2007 12:19 |
Ok.
I suggest having 2 types of docs: autogenerated from sources and manual. Manual articles may hypelink to source-autogenerated articles. All these docs are accessible by 3 tabs:
1. Index
indexed source-autogenerated articles;
2. Manual
manual docs, something like site with hyperlinks;
3. Search
full-text search within source and manual docs;
user may check areas for search: source, manual, or both.
Only tabs, no magic words. Plain and simple.
Is it OK, any corrections?
|
Sure, but I am not sure whether something like such plan is very important right now.
I mean, yes, we plan to produce more docs. We plan to implement better ways how to access it.
IMO, both 1. and 3. are already "initiated".
Mirek
|
|
|
|
|
|
| Re: Documentation and Topic++ [message #13041 is a reply to message #13038] |
Thu, 06 December 2007 21:05 |
zsolt
Messages: 702
Registered: December 2005
Location: Budapest, Hungary
|
Contributor |
|
|
| Novo wrote on Thu, 06 December 2007 20:05 |
| Mindtraveller wrote on Wed, 05 December 2007 12:19 |
Is it OK, any corrections?
|
Documentation in source code would be very handy.
One line per method (at least).
|
Current (separated) type of reference docs is very useful, I think. Some time ago I prefered doxygen docs of sources, but now, I don't care about it. The only problem is this tabbed help. Previous (windowed) version was better for me (using Alt+TAB is more easy, than clicking mouse). So I'm using online HTML docs currently.
Maybe it would be useful, to create a separate help viewer window or application with an "Edit" button, to allow editing topics, like in a wiki.
|
|
|
|
|
|
| Re: Documentation and Topic++ [message #13045 is a reply to message #13042] |
Thu, 06 December 2007 21:49 |
Novo
Messages: 1431
Registered: December 2006
|
Ultimate Contributor |
|
|
| luzr wrote on Thu, 06 December 2007 15:10 |
| Novo wrote on Thu, 06 December 2007 14:05 |
| Mindtraveller wrote on Wed, 05 December 2007 12:19 |
Is it OK, any corrections?
|
Documentation in source code would be very handy.
One line per method (at least).
|
Planned de facto equivalent of what you want.
Mirek
|
Do you mean "indexed source-autogenerated articles accessed via Topic++"?
No real documentation in source code, documentation is dynamically generated by Topic++?
Regards,
Novo
|
|
|
|
| Re: Documentation and Topic++ [message #13116 is a reply to message #12713] |
Wed, 12 December 2007 23:20 |
Mindtraveller
Messages: 917
Registered: August 2007
Location: Russia, Moscow rgn.
|
Experienced Contributor |
|
|
Writing "manual" help pages in current TheIDE version, what package should I add them to? I`d like these articles in the future to be "standalone" help articles accessible through "Manual" tab of new version of help system. Of course, after approval and changing of U++ authors.
For now, I`ve made different .tpp file, but didn`t find the way to open it not in view mode (not edit) and don`t know if it will be possible to move these articles to "manual" help mode.
[Updated on: Thu, 13 December 2007 02:19] Report message to a moderator |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Re: Documentation and Topic++ [message #16401 is a reply to message #16395] |
Thu, 12 June 2008 20:25 |
zsolt
Messages: 702
Registered: December 2005
Location: Budapest, Hungary
|
Contributor |
|
|
| luzr wrote on Thu, 12 June 2008 17:36 |
Well, this sounds good - for class browser.
Anyway, the goal I am currently pursuing is to show topic++ related to regular code editing. The idea is that in the left bar area, where breakpoints are, all lines with items with existing or even *potential* Topic++ entry will have an icon. Moving the mouse over that will display tooltip (rather big one  with help, clicking it will move you to the entry in Topic++ - if does not exist, it will create one.
Another issue is related to the need of community provided docs, so that we will finally start moving here... I guess it it will be very useful to be able to split source tree and topic tree (as option), so that all U++ docs can be kept and maintained separately (I think tha topic++ repository can have more relaxed access).
Mirek
|
I think, this is a very very good idea.
|
|
|
|
| Re: Documentation and Topic++ [message #16402 is a reply to message #16395] |
Thu, 12 June 2008 22:46 |
cbpporter
Messages: 1428
Registered: September 2007
|
Ultimate Contributor |
|
|
| luzr wrote on Thu, 12 June 2008 18:36 |
Well, this sounds good - for class browser.
|
Well this was more of an idea for the main documentation presentation, a replacement for the current structure of the Topic++ articles.
This is something of a solution to what I perceive as the tree main disadvantages of the current system:
1. It is far from complete (as in coverage of the API) and quite selective. Some parts are explained in great detail, while others are barely mentioned. It is also not uniform, neither as formating or style.
2. It is not that cross referenced. For example, when I'm browsing the SetStyle function for a class, I would like to have the definition of that style and a srcdoc style article related to what is Chameleon and how to use it, at my fingertips, both only a click way. When I'm browsing the documentation for String, I want to have a list will all the stand alone functions that work on string, preferably ordered by category. For example, I had often had a self written Join function, before I found out that there was one already implemented.
3. The current documentation for classes are hard to read because the text follows every method. This is daunting for someone new to the framework, who is trying to find something and has at least to skim through all that text. And is annoying for someone familiar with the framework, because these persons really don't need to have text displayed for the methods they already know.
But my idea and your approach are anyway not auto-exclusive. Both can use the same information, only the presentation is different. And the analogy with a browser is logical, since I was thinking of extending a browser window with an editor to enter a description for each item and a category for it. This meta information would them be used for the auto generated pages and could also allow atomic commits to that repository you talked about. When someone is using the normal browser, an icon could show that it has no documentation attached, and somebody might be willing to fill it out, submit it and not have to worry about formating or ruining something in a larger document.
Anyway, my ideas are heavily influenced by three really good help systems (IMHO): Delphi help files, PHP documentation and JavaDoc.
|
|
|
|
|
|
|
|
| Re: Documentation and Topic++ [message #16408 is a reply to message #16402] |
Fri, 13 June 2008 09:45 |
|
mirek
Messages: 14290
Registered: November 2005
|
Ultimate Member |
|
|
| cbpporter wrote on Thu, 12 June 2008 16:46 |
| luzr wrote on Thu, 12 June 2008 18:36 |
Well, this sounds good - for class browser.
|
Well this was more of an idea for the main documentation presentation, a replacement for the current structure of the Topic++ articles.
This is something of a solution to what I perceive as the tree main disadvantages of the current system:
1. It is far from complete (as in coverage of the API) and quite selective. Some parts are explained in great detail, while others are barely mentioned. It is also not uniform, neither as formating or style.
2. It is not that cross referenced. For example, when I'm browsing the SetStyle function for a class, I would like to have the definition of that style and a srcdoc style article related to what is Chameleon and how to use it, at my fingertips, both only a click way. When I'm browsing the documentation for String, I want to have a list will all the stand alone functions that work on string, preferably ordered by category. For example, I had often had a self written Join function, before I found out that there was one already implemented.
3. The current documentation for classes are hard to read because the text follows every method. This is daunting for someone new to the framework, who is trying to find something and has at least to skim through all that text. And is annoying for someone familiar with the framework, because these persons really don't need to have text displayed for the methods they already know.
But my idea and your approach are anyway not auto-exclusive. Both can use the same information, only the presentation is different. And the analogy with a browser is logical, since I was thinking of extending a browser window with an editor to enter a description for each item and a category for it. This meta information would them be used for the auto generated pages and could also allow atomic commits to that repository you talked about. When someone is using the normal browser, an icon could show that it has no documentation attached, and somebody might be willing to fill it out, submit it and not have to worry about formating or ruining something in a larger document.
Anyway, my ideas are heavily influenced by three really good help systems (IMHO): Delphi help files, PHP documentation and JavaDoc.
|
Well, I have to say that I have had "internal fight" between the two concepts for years - I mean, more database like concept of documentation as you suggest, where each method has its own entry, and document like approach like we have now.
In fact, a couple of years before, the first Topic++ iteration worked like database.
In the end, I prefer current model because of several tiny advantages (if they are advantages):
- you have little bit more flexible ways to organize docs. E.g. quite often it is nice to document a group of methods with single description.
- you have all formating capabilities of RichEdit, so you can put in pictures etc (well, this might be possible with some DB schemes as well I guess)
- and I think you are not really loosing the possiblity to present documentation in class browser JUST LIKE YOU SUGGEST - the topics++ are marked with code labels, so in fact existing topics can act as database too.
Mirek
P.S.: 2. - that is only a matter of putting these links into the text
[Updated on: Fri, 13 June 2008 09:47] Report message to a moderator |
|
|
|
|
|
| Re: Documentation and Topic++ [message #16440 is a reply to message #16437] |
Sun, 15 June 2008 19:03 |
mdelfede
Messages: 1310
Registered: September 2007
|
Ultimate Contributor |
|
|
I agree... IMHO the actual document structure isn't enough.
I'd prefere too a different approach, borland's user guides were very effective and comfortable to read... I think that could be a good example. Good old Microsoft guides in chm format were not bad at all too.
Maybe a good stuff would be to have a good underlying doc structure (maybe xml ?) ,separate viewer/browser AND separated doc editor.
We could even have more viewers, to accomodate user's preferences.
But, in my opinion, documents should be cathegorized, indexed and cross-referenced. Looking to a function/class should provide some "see-also" stuff, some examples, link to one or more main topics and so on.
And we should have cathegorized indexes.
Another good point would be to separate (as it was proposed sometimes) documentation from code, and give a more relaxed access to main repository's docs, allowing users to contribute more effectively.
We could even start a new sf project (with its svn repository) to hold just documentation for upp....
Max
|
|
|
|
|
|
Goto Forum:
Current Time: Sun Apr 26 06:18:15 GMT+2 2026
Total time taken to generate the page: 0.01456 seconds
|
U++ framework
Search
Help
Members
Register
Login
Home
