issue-#100 Review all the existing documentation

issue-#100 Review all the existing documentation

Postby Ivan Denisov » Tue Jan 26, 2016 10:26 am

http://redmine.blackboxframework.org/issues/100

I am starting to edit the existing documentation.

1. I fixed some typos in Tour.odc and remove Oberon logo
2. I removed Tut-Tot which duplicating the documentation (we can make some simple script for join Tut-*.odc files)
3. I added many links to subsections in Tut-TOC
4. I moved the demo view from sources of ObxCtrls to Docu file
+ small updates

Please, look at the last version here:
http://blackboxframework.org/unstable/issue-%23100/

and any suggestions about review of existing documentation are welcome.
Ivan Denisov
 
Posts: 1690
Joined: Tue Sep 17, 2013 12:21 am
Location: Russia

Re: issue-#100 Review all the existing documentation

Postby Ivan Denisov » Wed Jan 27, 2016 5:39 am

Ivan Denisov
 
Posts: 1690
Joined: Tue Sep 17, 2013 12:21 am
Location: Russia

Re: issue-#100 Review all the existing documentation

Postby Josef Templ » Wed Jan 27, 2016 1:19 pm

Docu/Tut-TOC
add a CR after Part III

Docu/Help
- Name the link to the Tutorial TOC 'Table of Contents' (Plural and Capital C)

- The Window title (link 'Table of Contents') should be adapted from 'Introduction' to what is really inside, e.g.
'BlackBox Tutorial - Table of Contents'

- I always found the Help start page confusing because it doesn't mention the term 'Tutorial' anywhere.
So I would like to propose to rephrase
'Component Software: A Case Study Using BlackBox Components'
to
'Tutorial: Component Software Using BlackBox Components'.
With that we get (1) a better symmetry between Tutorial and User Manual and (2) we avoid the term 'case study',
which is also confusing because it is a tutorial and not a case study.

System/Docu/User-Man
remove "Note that with the Classic Edition of BlackBox you need seperate licenses for each developer seat using the server installation."

license.txt
synchronize with to license.odc.

- Josef
User avatar
Josef Templ
 
Posts: 1957
Joined: Tue Sep 17, 2013 6:50 am

Re: issue-#100 Review all the existing documentation

Postby Zinn » Wed Jan 27, 2016 2:48 pm

I'm not agree with removing the Oberon Logo in the documents.
You may be change the module StdLogos and create a new picture like it was done with the icons and the about dialog.

Further I also not agree to remove the Mac part of the documentation, as long as it is not clear what other users think about it.
Maybe someone will program the mac part in the futures.

- Helmut
Zinn
 
Posts: 464
Joined: Tue Mar 25, 2014 5:56 pm
Location: Frankfurt am Main

Re: issue-#100 Review all the existing documentation

Postby Ivan Denisov » Wed Jan 27, 2016 3:49 pm

I updated the docu according Josef advices.

I am suggesting the title:
"Tutorial: Component Software on Example of BlackBox Components"

Also I tried to improve formatting of many documents and I removed all the Mac OS references except several general which are necessary for the discussion.

The version to try:
http://blackboxframework.org/unstable/i ... a1.400.zip
Ivan Denisov
 
Posts: 1690
Joined: Tue Sep 17, 2013 12:21 am
Location: Russia

Re: issue-#100 Review all the existing documentation

Postby Robert » Wed Jan 27, 2016 9:06 pm

A suggestion for handling this topic.

I think that many of us will, over time, have many comments on various Docu files. Most will be trivial typos, corrections, or clarifications that are obviously improvements.
A very few will be controversial.

To avoid have many sub-topics and votes in this forum I suggest we open a Wiki page and put our comments there as we think of them.
If anyone disagrees with a comment, just change it (it is a Wiki !), or maybe it is more polite to add a note saying you disagree, and maybe why.

Then, every few weeks, or when we have a good number of corrections, we collect the obvious ones together at one time, have one vote, and apply them all at the same time to the repository.
The few that lead to disagreements would then be discussed on this forum as usual.

Robert
User avatar
Robert
 
Posts: 968
Joined: Sat Sep 28, 2013 11:04 am
Location: Edinburgh, Scotland

Re: issue-#100 Review all the existing documentation

Postby Ivan Denisov » Thu Jan 28, 2016 6:15 am

Robert, for the existing documentation it is better if you correct the odc file. Then push it to repository or attach to the topic and I will push your changes to repository.

All the changes are available in our Redmine mirror:
http://redmine.blackboxframework.org/pr ... 1&type=sbs

It is easy to look that you like or not and discuss all here in forum. I do not like the idea about splitting the discussion for two places. The board is working now well for this, we should use it.

This Wiki strategy can be used for making new documentation files. But also, the DevSelectors experience showing that with board that is not difficult to make new documentation without using a Wiki.

If we put documentation to wiki there also will be the problem of synchronization Wiki version to internal BlackBox version. It is hard task, so I will not envy the person who will be responsible for this. I do not want to be such a person.
Ivan Denisov
 
Posts: 1690
Joined: Tue Sep 17, 2013 12:21 am
Location: Russia

Re: issue-#100 Review all the existing documentation

Postby Zinn » Thu Jan 28, 2016 6:44 am

I have change my mind.
Now I'm agree to remove the Mac description. The result is more readable.
You should also change the word modifier to ctrl.
Becareful don't do it on all places. Only there where is written about the key.

I still not agree about to remove the StdLogos. We may change the logo, but not remove it.
- Helmut
Zinn
 
Posts: 464
Joined: Tue Mar 25, 2014 5:56 pm
Location: Frankfurt am Main

Re: issue-#100 Review all the existing documentation

Postby Ivan Denisov » Thu Jan 28, 2016 6:55 am

Helmut, what for do you need it? It is hard to draw our yellow puzzle using Ports primitives. However we can try... Or you think, that we need another simplified logo?
Ivan Denisov
 
Posts: 1690
Joined: Tue Sep 17, 2013 12:21 am
Location: Russia

Re: issue-#100 Review all the existing documentation

Postby Josef Templ » Thu Jan 28, 2016 8:43 am

Ivan Denisov wrote:I updated the docu according Josef advices.

I am suggesting the title:
"Tutorial: Component Software on Example of BlackBox Components"

Also I tried to improve formatting of many documents and I removed all the Mac OS references except several general which are necessary for the discussion.


'Tutorial: Component Software Using BlackBox Components' still sounds better to me.
'Tutorial: Component Software on Example of BlackBox Components' does not sound like correct English to me.
Also there is now 'Example' instead of 'case study', which is not much different.
It is a tutorial on BlackBox. Why should it be declared an example or a case study?
What do our native speakers think?
May be an even shorter form like 'BlackBox Tutorial' would be best.


Regarding the MacOS parts:
It should be possible to run BlackBox under wine for MacOS, right?
Would anything from the MacOS part in the docu make still sense in such a context?

Removing the logo is OK for me.

- Josef
User avatar
Josef Templ
 
Posts: 1957
Joined: Tue Sep 17, 2013 6:50 am

Next

Return to Resolved (Documentation)

Who is online

Users browsing this forum: No registered users and 1 guest

cron