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 » Developing U++ » Documentation » Idea...
Idea... [message #22232] Fri, 26 June 2009 13:33 Go to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
Writing SQL tutorial, I have got an idea.

I have to admit I have problems writing those explanation texts - partly because of my english literacy, partly because it is sometimes harder for me to sort out things that require explanation in deeper detail.

So I have got an idea: what about if I would only provide source code examples and maybe provisional section titles and somebody else would fill the explanation?

(for hints how the result should look like, try http://www.ultimatepp.org/srcdoc$Sql$tutorial$en-us.html)

Also, related:

If you have any suggestion about extending existing tutorials, let me know...

Mirek
Re: Idea... [message #22268 is a reply to message #22232] Mon, 29 June 2009 08:36 Go to previous messageGo to next message
koldo is currently offline  koldo
Messages: 3355
Registered: August 2008
Senior Veteran
Hello Mirek

- One thing I would like is to have a documentation full copy in one file. It would be easy to handle and print.

- Other thing we have been talking about is to have a clear "Contents". Through "Contents" it is:
1. Easier to look for info
2. We can include also subjects to be included, so it would be easier for new documentators to choose in which area the can help

- Mirek, Please do a "Contents" with areas now documented and not documented. After that ask the people to choose what they want to document. We have there a good "Contents" sample in http://www.ultimatepp.org/forum/index.php?t=msg&goto=216 89&.

Just move it on Smile

Best regards
Koldo


Best regards
Iñaki
Re: Idea... [message #22270 is a reply to message #22268] Mon, 29 June 2009 09:10 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
koldo wrote on Mon, 29 June 2009 02:36

Hello Mirek

- One thing I would like is to have a documentation full copy in one file. It would be easy to handle and print.

- Other thing we have been talking about is to have a clear "Contents". Through "Contents" it is:
1. Easier to look for info
2. We can include also subjects to be included, so it would be easier for new documentators to choose in which area the can help

- Mirek, Please do a "Contents" with areas now documented and not documented. After that ask the people to choose what they want to document. We have there a good "Contents" sample in http://www.ultimatepp.org/forum/index.php?t=msg&goto=216 89&.

Just move it on Smile

Best regards
Koldo


Well, just tell where it does fit... I mean, I can imagine the content on website.

It is however maybe a little bit more problematic as part of help system: There is still an idea that documentation is modular, therefore each package has its docs and packages can be added / removed as needed...

Mirek
Re: Idea... [message #22271 is a reply to message #22270] Mon, 29 June 2009 10:08 Go to previous messageGo to next message
koldo is currently offline  koldo
Messages: 3355
Registered: August 2008
Senior Veteran
luzr wrote on Mon, 29 June 2009 09:10

koldo wrote on Mon, 29 June 2009 02:36

Hello Mirek

- One thing I would like is to have a documentation full copy in one file. It would be easy to handle and print.

- Other thing we have been talking about is to have a clear "Contents". Through "Contents" it is:
1. Easier to look for info
2. We can include also subjects to be included, so it would be easier for new documentators to choose in which area the can help

- Mirek, Please do a "Contents" with areas now documented and not documented. After that ask the people to choose what they want to document. We have there a good "Contents" sample in http://www.ultimatepp.org/forum/index.php?t=msg&goto=216 89&.

Just move it on Smile

Best regards
Koldo


Well, just tell where it does fit... I mean, I can imagine the content on website.

It is however maybe a little bit more problematic as part of help system: There is still an idea that documentation is modular, therefore each package has its docs and packages can be added / removed as needed...

Mirek


Hello Mirek

Using the qprentice "Contents" proposal in http://www.ultimatepp.org/forum/index.php?t=msg&goto=216 89&. you can define the main structure and fill it with the existing help contents and a simple empty screen with a "To Be Documented" in the chapters not documented yet.

Then you can ask people to fill those gaps or to add new chapters that fit in the main "Contents" structure. Bazaar documents could fit in an "Appendix" section at the end.

And it could be great the possibility to hardcopy all in a single document that can be copied and printed as a whole. You can publish it and earn a bunch of money! Smile

Best regards
Koldo


Best regards
Iñaki
Re: Idea... [message #22275 is a reply to message #22271] Mon, 29 June 2009 13:42 Go to previous messageGo to next message
gprentice is currently offline  gprentice
Messages: 260
Registered: November 2005
Location: New Zealand
Experienced Member
I'm still interested in this issue too but I'm struggling to find time so far.

My feeling is that U++ needs a conventional help system orthogonal to the existing help system and I was hoping to think of a way of sharing the doc pages between each. As I've probably said more than once, the information you need to get started with U++ is hard to find and I think a quick start section that explains the basics of theIDE, setting up a compiler (what compilers are supported?) and building a simple application would help. Plus a help button for the "set main package dialog" ...

I suspect the reference topics could be linked to a second help system automatically but the "documentation" topics would need manual linking to the second help system. Also, it would be nice if the help system could have the attractive appearance that pspad help has
http://www.pspad.com/en/helpfiles.htm
plus "history", user bookmarks, better searching...

Graeme
Re: Idea... [message #22277 is a reply to message #22275] Mon, 29 June 2009 19:38 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
gprentice wrote on Mon, 29 June 2009 07:42

I'm still interested in this issue too but I'm struggling to find time so far.

My feeling is that U++ needs a conventional help system orthogonal to the existing help system and I was hoping to think of a way of sharing the doc pages between each. As I've probably said more than once, the information you need to get started with U++ is hard to find and I think a quick start section that explains the basics of theIDE, setting up a compiler (what compilers are supported?) and building a simple application would help. Plus a help button for the "set main package dialog" ...

I suspect the reference topics could be linked to a second help system automatically but the "documentation" topics would need manual linking to the second help system. Also, it would be nice if the help system could have the attractive appearance that pspad help has
http://www.pspad.com/en/helpfiles.htm
plus "history", user bookmarks, better searching...

Graeme



I think there is little needed to achieve that.

I guess, having such manual on www is as good as anything else (but we can easily provide PDF export too).

All it takes is somebody brave starting the content page in uppweb...

Mirek
Re: Idea... [message #22715 is a reply to message #22232] Sat, 08 August 2009 02:49 Go to previous message
pveach1 is currently offline  pveach1
Messages: 10
Registered: August 2009
Promising Member
Hi All,
If this topic isn't dead I'd like to add my 2 cents.

I prefer CHM compiled help files and PDF files. In that order.
With a chm file you can have the help open on one monitor while theIDE is open on another. Second, you can have more than on CHM file open at a time, with PDFs they open in the same App.

Lastly, as regards writing, the problem is that the subject is so abstract that it makes it hard not to wander about a bit. One solution might be to take a specific piece of code (starting with the most commonly used senario) and explain what is going on in that code. Once that is done, then cover a more advanced or less common usage. The specific code fragment keeps you focused.

cheers Mirek et al
Previous Topic: an error in manual
Next Topic: Mistake in Character Set Support Documentation
Goto Forum:
  


Current Time: Fri Mar 29 13:53:41 CET 2024

Total time taken to generate the page: 0.01656 seconds