|
|
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 |
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 #14696 is a reply to message #14600] |
Sun, 09 March 2008 14:00 |
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 |
|
mirek
Messages: 13984 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 #14716 is a reply to message #14710] |
Mon, 10 March 2008 11:13 |
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
|
|
|
Goto Forum:
Current Time: Mon Jun 10 13:58:06 CEST 2024
Total time taken to generate the page: 0.01831 seconds
|
|
|