|
|
Home » Developing U++ » Documentation » Improving the organization of U++ help
Improving the organization of U++ help [message #21638] |
Sat, 30 May 2009 15:39 |
gprentice
Messages: 260 Registered: November 2005 Location: New Zealand
|
Experienced Member |
|
|
Here's what I think a properly organised U++ "help" would look like. It's very likely to be incomplete and I'm not offering to do any of the work (right now)!
1. Introduction
1.1 Overview of U++. (no major details)
U++ is C++ development platform for creating console or GUI applications
- written entirely in C++ using modern techniques.
Platforms supported.
Compilers and compiler versions supported.
U++ IDE is called "theIDE" and is built with U++.
Includes comprehensive editor, build system and project management.
Design philosophy - emphasis is on "rapid development"? What about runtime performance? How does "objects are on the stack" philosophy affect code size?
Look and feel / chameleon
Visual designer
Database capability
Multithreading issues
NTL ??
Link to list of all widgets - what widgets are missing.
Image designer.
Core values and containers - what are they? - link to tutorials.
Non GUI libraries (important ones) - SQL, Web etc - link to packages list
Assist++ - sophisticated source navigation.
Topic++
Blitz & uld.
1.2 Using help. What is "documents", "reference", "implementation".
What generates the stuff in the help tree control (what is "used packages",
what is "other packages", is this list context dependent)
Link to "topic++" topic and explain better how source code is linked to documentation. How to search help.
1.3 Creating a simple project from scratch - say, the button example, and run it.
(include setting up the compiler and the build mode).
1.4 Library orginization.
What is "core". what is ctrllib. what is ctrlcore etc.
1.5 Project organization
Summarise packages and assemblies.
1.6 List of tutorials
1.7 Why U++ exists, who is using it.
1.8 Obtaining and installing U++
include how to get updates from google code.
1.9 Deploying U++ apps.
1.10 Examples & references
Explain about them.
2. Using theIDE
2.1 Describe main components of theIDE UI.
Explain what all the toolbars do (including "aux" thing) and package lists.
How to select a project (describe select package dialog).
Describe all menu options.
Describe how to turn off an on all toolbars
(why is there no "view" menu and no close button on the toolbars?)
2.2 Keyboard shortcuts
2.2 Using the editor.
Mention auto-saving.
2.3 Layout designer
2.4 Image designer
2.5 theIDE command line & UMK
2.6 cross development topic
2.7 File types
3. Project/package organization & configuration & building & debugging
3.1 Packages, assemblies & nests
3.2 Configuring packages, assemblies
3.3 Setting compiler options & build flags
3.4 Building - where does output go. Can I edit while building?
3.5 Package templates
3.6 Debugging
4. Creating a GUI application
- GUI tutorial
5. Widgets
6. ESC scripting
- include "theIDE macros" topic from "theIDE help"
7. Library/ API reference & docs
Core, ctrlcore etc
8. Extending U++.
--
Graeme
|
|
|
Re: Improving the organization of U++ help [message #21645 is a reply to message #21638] |
Sat, 30 May 2009 22:39 |
|
mirek
Messages: 14039 Registered: November 2005
|
Ultimate Member |
|
|
gprentice wrote on Sat, 30 May 2009 09:39 |
Here's what I think a properly organised U++ "help" would look like. It's very likely to be incomplete and I'm not offering to do any of the work (right now)!
1. Introduction
1.1 Overview of U++. (no major details)
U++ is C++ development platform for creating console or GUI applications
- written entirely in C++ using modern techniques.
Platforms supported.
Compilers and compiler versions supported.
U++ IDE is called "theIDE" and is built with U++.
Includes comprehensive editor, build system and project management.
Design philosophy - emphasis is on "rapid development"? What about runtime performance? How does "objects are on the stack" philosophy affect code size?
Look and feel / chameleon
Visual designer
Database capability
Multithreading issues
NTL ??
Link to list of all widgets - what widgets are missing.
Image designer.
Core values and containers - what are they? - link to tutorials.
Non GUI libraries (important ones) - SQL, Web etc - link to packages list
Assist++ - sophisticated source navigation.
Topic++
Blitz & uld.
1.2 Using help. What is "documents", "reference", "implementation".
What generates the stuff in the help tree control (what is "used packages",
what is "other packages", is this list context dependent)
Link to "topic++" topic and explain better how source code is linked to documentation. How to search help.
1.3 Creating a simple project from scratch - say, the button example, and run it.
(include setting up the compiler and the build mode).
1.4 Library orginization.
What is "core". what is ctrllib. what is ctrlcore etc.
1.5 Project organization
Summarise packages and assemblies.
1.6 List of tutorials
1.7 Why U++ exists, who is using it.
1.8 Obtaining and installing U++
include how to get updates from google code.
1.9 Deploying U++ apps.
1.10 Examples & references
Explain about them.
2. Using theIDE
2.1 Describe main components of theIDE UI.
Explain what all the toolbars do (including "aux" thing) and package lists.
How to select a project (describe select package dialog).
Describe all menu options.
Describe how to turn off an on all toolbars
(why is there no "view" menu and no close button on the toolbars?)
2.2 Keyboard shortcuts
2.2 Using the editor.
Mention auto-saving.
2.3 Layout designer
2.4 Image designer
2.5 theIDE command line & UMK
2.6 cross development topic
2.7 File types
3. Project/package organization & configuration & building & debugging
3.1 Packages, assemblies & nests
3.2 Configuring packages, assemblies
3.3 Setting compiler options & build flags
3.4 Building - where does output go. Can I edit while building?
3.5 Package templates
3.6 Debugging
4. Creating a GUI application
- GUI tutorial
5. Widgets
6. ESC scripting
- include "theIDE macros" topic from "theIDE help"
7. Library/ API reference & docs
Core, ctrlcore etc
8. Extending U++.
--
Graeme
|
I believe this is a good idea & start. We should build on this.
Just, please, do not expect all docs to be written by me. I believe I can do part of reference docs and most library tutorials.
Mirek
|
|
|
|
Re: Improving the organization of U++ help [message #21648 is a reply to message #21645] |
Sun, 31 May 2009 01:36 |
gprentice
Messages: 260 Registered: November 2005 Location: New Zealand
|
Experienced Member |
|
|
luzr wrote on Sun, 31 May 2009 08:39 |
I believe this is a good idea & start. We should build on this.
Just, please, do not expect all docs to be written by me. I believe I can do part of reference docs and most library tutorials.
Mirek
|
ok. So how will it be organized? Can the existing help have two modes - one that has full index in the tree control and one that has "package restricted" index like at present. Is it possible to auto-generate a pdf of the whole lot - including indexed table of contents. If pdf is too hard or nobody has acrobat pro, then html like the website.
As koldo mentioned, for people to contribute there needs to be a way of letting people assign tasks to themselves so there's no doubling up. Also, since most people can't predict when they'll get time to work on it, maybe an expected completion date could be posted so if someone else gets keen to help, they can. Even a revision control like system so people can check out topics for updating without fear their work will conflict with someone else's.
Also, the "help outline" I posted probably needs refining. Once the table of contents is agreed to, it should be created, with skeleton pages for everything so hyper-links can be used.
Is it possible to have a search mode in the help that restricts to finding function names. You can do this in theIDE right? How do you get from the IDE list to the help topic for the function.
As well as table of contents, an index would be nice. Is there any way to insert a (hidden) marker anywhere within a topic that includes a name that would appear in the index - maybe with a category too so that the index can separate API/ function names from the rest.
There's already a lot of documentation and it might not take a lot to fill in the gaps. The focus of the website could then change slightly to have "1.1 Overview of U++" in a prominent place so people can immediately see quickly what U++ is all about.
Graeme
|
|
|
Re: Improving the organization of U++ help [message #21650 is a reply to message #21648] |
Sun, 31 May 2009 09:10 |
|
mirek
Messages: 14039 Registered: November 2005
|
Ultimate Member |
|
|
gprentice wrote on Sat, 30 May 2009 19:36 |
luzr wrote on Sun, 31 May 2009 08:39 |
I believe this is a good idea & start. We should build on this.
Just, please, do not expect all docs to be written by me. I believe I can do part of reference docs and most library tutorials.
Mirek
|
ok. So how will it be organized?
|
I guess for starters, you can use what we have, just add one T++ topic with this summary that links to existing parts, leave non-existing topics without links.
This will immediately generate it to www.
Quote: |
Can the existing help have two modes - one that has full index in the tree control and one that has "package restricted" index like at present.
|
It is not package restricted anymore, rather 'assembly restricted' - and that is for all purposes ok as long as you have uppsrc in the list.
Quote: |
Is it possible to auto-generate a pdf of the whole lot - including indexed table of contents. If pdf is too hard or nobody has acrobat pro, then html like the website.
|
With some effort, yes.
Quote: |
As koldo mentioned, for people to contribute there needs to be a way of letting people assign tasks to themselves so there's no doubling up. Also, since most people can't predict when they'll get time to work on it, maybe an expected completion date could be posted so if someone else gets keen to help, they can. Even a revision control like system so people can check out topics for updating without fear their work will conflict with someone else's.
|
Maybe, but with current "traffic" this is now least of concerns..
Quote: |
Is it possible to have a search mode in the help that restricts to finding function names. You can do this in theIDE right? How do you get from the IDE list to the help topic for the function.
|
Ehm, this is what "finishing" T++ was about?
Quote: |
As well as table of contents, an index would be nice. Is there any way to insert a (hidden) marker anywhere within a topic that includes a name that would appear in the index - maybe with a category too so that the index can separate API/ function names from the rest.
|
Yes. "Index entry"
Mirek
|
|
|
Re: Improving the organization of U++ help [message #21652 is a reply to message #21650] |
Sun, 31 May 2009 11:39 |
gprentice
Messages: 260 Registered: November 2005 Location: New Zealand
|
Experienced Member |
|
|
Quote: | I guess for starters, you can use what we have, just add one T++ topic with this summary that links to existing parts, leave non-existing topics without links.
|
Add a topic? Where? How?
Links? You mean a hyperlink? So you can't have a topic such as "Moveable" appearing directly in both UsedPackages->Core->Documents as well as in UserManual->Library->Overview->Moveable?
Quote: |
Quote: |
Is it possible to auto-generate a pdf of the whole lot - including indexed table of contents. If pdf is too hard or nobody has acrobat pro, then html like the website.
|
With some effort, yes.
|
Would it be automated?
Quote: | Maybe, but with current "traffic" this is now least of concerns..
|
Well if documentation is better organized, traffic might improve because people will be able to see what needs doing and also will be able to more easily find the topic they have something to contribute on. If people think their work will be ignored (as some of the tutorials contributed in the past have been) or conflict with someone else, they're not gonna be interested in contributing. A visible process is needed.
Will contributions and modifications be accepted blindly without checking? Revision control would help a lot.
Quote: | Ehm, this is what "finishing" T++ was about?
|
I've only loosely been following Upp for the last 3 years so I don't know what's been done. Do you think you could spell it out for me?
Say I put the cursor on the call to Add in button.cpp example, and press Ctrl Q. It shows two Add functions in the navigator bar. Click one and I get taken to the code. Click the little blue square box and I go to the topic++ editor for the docs for that function. How do I get to the help info for that function without being in topic++ editor mode? (yes, I know mouse-over of the little blue box gives a popup but I want to jump into the help).
I see the "index entry" combo box in the topic++ editor and I notice stuff turns green where I've inserted "indexes" but I don't see any index turning up anywhere and no info about it in the help for topic++.
Another problem is if you enter a search term in the help search box, the term isn't highlighted in the topic content window and there's no way to step forward and backwards through the list of matches like most search mechanisms have.
Graeme
|
|
|
Re: Improving the organization of U++ help [message #21655 is a reply to message #21652] |
Sun, 31 May 2009 13:16 |
|
mirek
Messages: 14039 Registered: November 2005
|
Ultimate Member |
|
|
gprentice wrote on Sun, 31 May 2009 05:39 |
Quote: | I guess for starters, you can use what we have, just add one T++ topic with this summary that links to existing parts, leave non-existing topics without links.
|
Add a topic? Where? How?
Links? You mean a hyperlink? So you can't have a topic such as "Moveable" appearing directly in both UsedPackages->Core->Documents as well as in UserManual->Library->Overview->Moveable?
|
What is "UserManual->Library->Overview->Moveable"?
Do you propose multiple trees?
I am afraid this would lead to requests to T++ that will take a lot of time to implement.
Meanwhile, I think that for most SW products docs, hyperlinks are enough to maintain logical structure.
Quote: |
Quote: |
Quote: |
Is it possible to auto-generate a pdf of the whole lot - including indexed table of contents. If pdf is too hard or nobody has acrobat pro, then html like the website.
|
With some effort, yes.
|
Would it be automated?
|
Can be. Not harder than html->pdf conversion, obviously.
Quote: |
Quote: | Maybe, but with current "traffic" this is now least of concerns..
|
Well if documentation is better organized, traffic might improve because people will be able to see what needs doing and also will be able to more easily find the topic they have something to contribute on. If people think their work will be ignored (as some of the tutorials contributed in the past have been) or conflict with someone else, they're not gonna be interested in contributing. A visible process is needed.
|
Come on. svn is good enough to manage source contributions. I do not see docs any harder.
Quote: |
Will contributions and modifications be accepted blindly without checking? Revision control would help a lot.
|
Sure, svn. All this infrastrucre exists for more than 8 months.
Quote: |
Quote: | Ehm, this is what "finishing" T++ was about?
|
I've only loosely been following Upp for the last 3 years so I don't know what's been done. Do you think you could spell it out for me?
|
Ah, I see. Well, what about just scanning this "Documentation" forum for details?
Quote: |
How do I get to the help info for that function without being in topic++ editor mode? (yes, I know mouse-over of the little blue box gives a popup but I want to jump into the help).
|
Well, nobody suggested this yet. Can be added.
Quote: |
I see the "index entry" combo box in the topic++ editor and I notice stuff turns green where I've inserted "indexes" but I don't see any index turning up anywhere and no info about it in the help for topic++.
|
Not yet implemented. Besides, in reality, full-text search is perhaps better..
Quote: |
Another problem is if you enter a search term in the help search box, the term isn't highlighted in the topic content window and there's no way to step forward and backwards through the list of matches like most search mechanisms have.
|
Yep. Actually, help browser is still a bit lacking. From time to time, various people suggested taking a care about it, that is why I did not got involved yet...
Mirek
|
|
|
|
|
|
|
|
Re: Improving the organization of U++ help [message #21686 is a reply to message #21669] |
Mon, 01 June 2009 02:49 |
gprentice
Messages: 260 Registered: November 2005 Location: New Zealand
|
Experienced Member |
|
|
luzr wrote |
Quote: |
I'm not familiar with using svn with U++. Topic++ files are binary aren't they.
|
Not anymore, that was part of creating new infrastructure. Diff would work with them just OK (but of course, you would have to deal with raw QTF to solve conflicts - nothing too hard anyway).
|
Great. (how are images handled?)
luzr wrote |
I believe that current documentation infrastructure, while not perfect, is good enough. What is missing is content
|
What is the main content that you think is missing?
luzr wrote |
Basically everybody with any write access to svn gains rights to edit documentation. Ditto for website.
|
Forgive my ignorance but what does "ditto for website" mean?
koldo wrote |
Just a list of documentation to be done linked to the Summary and an opportunity to sign in some place and say YES!, I will do this in four weeks!. The developer of that code only should have to check the new documentation.
|
Google code issue tracking is a possibility for this
http://code.google.com/p/upp-mirror/issues/list
People could post documentation deficiencies there and also create issues where they post updated information for the help if they don't have time to check in updated documentation. Posting a thread in (this) documentation forum would probably work too .
Graeme
[Updated on: Mon, 01 June 2009 02:50] Report message to a moderator
|
|
|
Re: Improving the organization of U++ help [message #21689 is a reply to message #21686] |
Mon, 01 June 2009 08:22 |
|
mirek
Messages: 14039 Registered: November 2005
|
Ultimate Member |
|
|
gprentice wrote on Sun, 31 May 2009 20:49 |
luzr wrote |
Quote: |
I'm not familiar with using svn with U++. Topic++ files are binary aren't they.
|
Not anymore, that was part of creating new infrastructure. Diff would work with them just OK (but of course, you would have to deal with raw QTF to solve conflicts - nothing too hard anyway).
|
Great. (how are images handled?)
|
Badly - as before. OTOH, given that content of images rarely changes within them, I suppose that diff would work in most cases too - these blocks would either be equal as whole or different as whole.
Sidenote: So far, for the code and documentation, revision conflicts proved to be much less concern than I originally anticipated. I mean, they do not happen all that often, even if the whole issue is unmanaged.
Quote: |
luzr wrote |
I believe that current documentation infrastructure, while not perfect, is good enough. What is missing is content
|
What is the main content that you think is missing?
|
I guess I am not a good one to ask. But from my point of view, I have planned following articles:
- Community manual. Started writing one in uppbox.
- Contributors manual.
- reference docs
- Sql tutorial (started this one yesterday)
- Painter tutorial
- Drag&Drop tutorial
- "Against manual resource management" article (explaining U++ programming style and typical patterns represented in it).
Quote: |
luzr wrote |
Basically everybody with any write access to svn gains rights to edit documentation. Ditto for website.
|
Forgive my ignorance but what does "ditto for website" mean?
|
Everybody with svn write access can alter the website. Website is generated each night from uppbox/uppweb.
Mirek
[Updated on: Mon, 01 June 2009 08:22] Report message to a moderator
|
|
|
Goto Forum:
Current Time: Sat Sep 21 02:17:56 CEST 2024
Total time taken to generate the page: 0.00734 seconds
|
|
|