U++ forum: Welcome to the forum

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

Report message to a moderator