Overview
Examples
Screenshots
Comparisons
Applications
Download
Documentation
Tutorials
Bazaar
Status & Roadmap
FAQ
Authors & License
Forums
Funding Ultimate++
Search on this site
Search in forums












SourceForge.net Logo
Home » U++ TheIDE » U++ TheIDE: Other Features Wishlist and/or Bugs » An idea for improved documentation
An idea for improved documentation [message #14600] Tue, 04 March 2008 14:09 Go to next message
mdelfede is currently offline  mdelfede
Messages: 1307
Registered: September 2007
Ultimate Contributor
After some time spent in Upp coding, I realized that the most of time I spend is trying to find what undocumented stuffs do, or even worse, to recode stuffs that are already present in Upp but not documented.
So, I got a small idea about setting up a sort of doc svn site with public write access, so everyone could improve the docs while using Upp.
For me it would be no cost to update docs while I use code, and that would be confortable to have it handy on succesful uses, instead of having (as for now...) some flying pieces of paper with hand annotations!
The best, IMHO, would be to setup an HTML tree with just all classes, functions headers and so, put on a svn server and hope (-:)) that people using it will update it with explanations, hints, samples and caveats.
The first step could be done automatically, scanning the source three. I think that all that could then be converted in upp-style docs, and even on .chm for windows users.
What do you think about ?

Max
Re: An idea for improved documentation [message #14631 is a reply to message #14600] Wed, 05 March 2008 09:20 Go to previous messageGo to next message
Mindtraveller is currently offline  Mindtraveller
Messages: 917
Registered: August 2007
Location: Russia, Moscow rgn.
Experienced Contributor

This is very close to what I and some other people proposed earlier. So I vote for this.
Besides, the first thing we should really do - open wide discussion about docs and tools for them. HTML is good choice, but we need appropriate tools for easy creating template-based html documents, with easy creating locale-based links between documents. More, we need some coordination center or paper, regulating docs structure, the way the should grow - or we`ll have real mess after a dozen of updates by different people..
Re: An idea for improved documentation [message #14632 is a reply to message #14631] Wed, 05 March 2008 09:23 Go to previous messageGo to next message
Mindtraveller is currently offline  Mindtraveller
Messages: 917
Registered: August 2007
Location: Russia, Moscow rgn.
Experienced Contributor

I`ve reminded a good phrase told me by sergeynikitin. I agree that big projects have manuals/docs discussion as big as all others discussions together. This should be understood because good docs is what brings U++ to a new level of usage and spreading between programmers worldwide.
Re: An idea for improved documentation [message #14692 is a reply to message #14632] Sun, 09 March 2008 08:40 Go to previous messageGo to next message
waxblood is currently offline  waxblood
Messages: 95
Registered: January 2007
Member

Instead of using a svn server of html docs, wouldn't be better to use the wiki, which is specifically designed for this type of collaborative work?

I think in this - and in many other projects - there's a useless duplication of information between manual, forum and wiki. The wiki seems IMO the best way to publish and organize information, so I would auspicate a conversion filter between upp docs files and the wiki. Don't know how much work this would require, for sure many people who have to share information about their upp-related projects would like a similar solution.

Unfortunatley I don't have time to write any code at present, this is just an idea.


David
Re: An idea for improved documentation [message #14693 is a reply to message #14692] Sun, 09 March 2008 11:14 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
Well, I think that global storage for docs is a good idea, regardless of method used.

In the same time, I believe that it is also a good idea to retain and extend theide's capability of creating documents and connecting them with the code.

I think that this perhaps leads to "upload" button in Topic++ Smile

Mirek
Re: An idea for improved documentation [message #14694 is a reply to message #14692] Sun, 09 March 2008 11:23 Go to previous messageGo to next message
mdelfede is currently offline  mdelfede
Messages: 1307
Registered: September 2007
Ultimate Contributor
I think the best and the simplest (for now) would be to put upp docs in upp format on a svn server.
Converting them to Html should be quite simple, then, if we want to have html docs too. The way around (from html to upp) would be almost impossible.
Having docs in a simple format (even xml would be good) could make it possible to convert docs in many format.

What we need is a way to add docs from inside theide in a SIMPLE way, and a SIMPLE way (just a click...) to update a repository with it. No need to have same format in Upp and in repository, just some sort of easy-to-convert format (which is not the case of html).
The wiki could then be kept updated by simple scripts running daily.

Example of a cycle :
1- you need a function that does something... you look in docs, none. You search in upp code (what for now happens often), and you find it undocumented.
2- just select some 'add doc to item' menu item, and than have an input dialog to add some docs.
3- press a button and update central repo

Ciao

Max
Re: An idea for improved documentation [message #14696 is a reply to message #14600] Sun, 09 March 2008 14:00 Go to previous messageGo to next message
darkwyrm is currently offline  darkwyrm
Messages: 3
Registered: February 2008
Junior Member
The format, if you asked me, doesn't really make a difference so long as it makes documentation less work, but wanting to have documentation accessible on the WWW in addition to right in TheIDE makes sense. No one I know really likes to work on documentation (except maybe me, perhaps), so having a collaborative effort would help a lot.

What about having a feature in TheIDE that is more or less a frontend to SVN (or CVS or whatever) for the documentation? You could make changes to the documentation from Topic++ and upload them to a "master" copy would make updates more timely -- you tend to notice problems while you're looking for something else in the documentation. This would allow you to also have a menu item which could update the documentation from the server. In addition, HTML pages could be updated from the documentation as checkins arrive. Collaborative like a wiki but allowing you to keep your own documentation up-to-date like SVN.

I'm new here, but I've done active BeOS application development for the last 6 or so years. I can safely say that the most frustrating thing about the U++ project is not being able to find information about something. The documentation needs help. Some sections are really good, but some aren't at all well-organized, others are incomplete or not at all helpful, and some sections are completely missing. U++'s learning curve is very steep because of this. I'd like to help fix that, but I can't seem to find any info on how to contribute to U++.

DarkWyrm
Re: An idea for improved documentation [message #14710 is a reply to message #14694] Mon, 10 March 2008 09:30 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
mdelfede wrote on Sun, 09 March 2008 06:23

I think the best and the simplest (for now) would be to put upp docs in upp format on a svn server.
Converting them to Html should be quite simple, then, if we want to have html docs too. The way around (from html to upp) would be almost impossible.
Having docs in a simple format (even xml would be good) could make it possible to convert docs in many format.

What we need is a way to add docs from inside theide in a SIMPLE way, and a SIMPLE way (just a click...) to update a repository with it. No need to have same format in Upp and in repository, just some sort of easy-to-convert format (which is not the case of html).
The wiki could then be kept updated by simple scripts running daily.



You would not need to run scripts, just run existing website generator daily...

Quote:


Example of a cycle :
1- you need a function that does something... you look in docs, none. You search in upp code (what for now happens often), and you find it undocumented.
2- just select some 'add doc to item' menu item, and than have an input dialog to add some docs.
3- press a button and update central repo



Yes. The only trouble I see is the "way back" - it should be possible update actual version of docs first, before making any changes.

Mirek
Re: An idea for improved documentation [message #14712 is a reply to message #14696] Mon, 10 March 2008 09:39 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
darkwyrm wrote on Sun, 09 March 2008 09:00

The format, if you asked me, doesn't really make a difference so long as it makes documentation less work, but wanting to have documentation accessible on the WWW in addition to right in TheIDE makes sense.



There is no problem there. Documentation on the website is generated from the documentation in theide. So all we have to do is to keep existing format... (and then create a daemon that updates website each night).

Quote:


What about having a feature in TheIDE that is more or less a frontend to SVN (or CVS or whatever) for the documentation? You could make changes to the documentation from Topic++ and upload them to a "master" copy would make updates more timely -- you tend to notice problems while you're looking for something else in the documentation. This would allow you to also have a menu item which could update the documentation from the server. In addition, HTML pages could be updated from the documentation as checkins arrive. Collaborative like a wiki but allowing you to keep your own documentation up-to-date like SVN.



Well, I guess this is what we all agree about Smile

Unfortunately, the first step on this road is to make 2008.1 release and then to improve C++ parser.

Mirek
Re: An idea for improved documentation [message #14716 is a reply to message #14710] Mon, 10 March 2008 11:13 Go to previous message
mdelfede is currently offline  mdelfede
Messages: 1307
Registered: September 2007
Ultimate Contributor
luzr wrote on Mon, 10 March 2008 09:30

mdelfede wrote on Sun, 09 March 2008 06:23

I think the best and the simplest (for now) would be to put upp docs in upp format on a svn server.
Converting them to Html should be quite simple, then, if we want to have html docs too. The way around (from html to upp) would be almost impossible.
Having docs in a simple format (even xml would be good) could make it possible to convert docs in many format.

What we need is a way to add docs from inside theide in a SIMPLE way, and a SIMPLE way (just a click...) to update a repository with it. No need to have same format in Upp and in repository, just some sort of easy-to-convert format (which is not the case of html).
The wiki could then be kept updated by simple scripts running daily.



You would not need to run scripts, just run existing website generator daily...

Quote:


Example of a cycle :
1- you need a function that does something... you look in docs, none. You search in upp code (what for now happens often), and you find it undocumented.
2- just select some 'add doc to item' menu item, and than have an input dialog to add some docs.
3- press a button and update central repo



Yes. The only trouble I see is the "way back" - it should be possible update actual version of docs first, before making any changes.

Mirek



Well, svn can cope quite well with automatic merging of text files... you could update local copy on ide launch and maybe on a time basis while ide is running.
Or, maybe better, just on demand and before updating remote repo, so in there's some double posting the user can correct it.
We could also keep newest parts of docs flagged as "unstable" for some time, so users can know that docs must still be reviewed before being considered stable.

Max

Previous Topic: [BUG] Command in temp-aux's context menu
Next Topic: Drag and Drop files
Goto Forum:
  


Current Time: Thu Mar 28 16:31:51 CET 2024

Total time taken to generate the page: 0.01385 seconds