issue-#100 Review all the existing documentation

Post Reply
Ivan Denisov
Posts: 1700
Joined: Tue Sep 17, 2013 12:21 am
Location: Russia

issue-#100 Review all the existing documentation

Post by Ivan Denisov »

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: 1700
Joined: Tue Sep 17, 2013 12:21 am
Location: Russia

Re: issue-#100 Review all the existing documentation

Post by Ivan Denisov »

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

Re: issue-#100 Review all the existing documentation

Post by Josef Templ »

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
Zinn
Posts: 476
Joined: Tue Mar 25, 2014 5:56 pm
Location: Frankfurt am Main
Contact:

Re: issue-#100 Review all the existing documentation

Post by Zinn »

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
Ivan Denisov
Posts: 1700
Joined: Tue Sep 17, 2013 12:21 am
Location: Russia

Re: issue-#100 Review all the existing documentation

Post by Ivan Denisov »

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
User avatar
Robert
Posts: 1024
Joined: Sat Sep 28, 2013 11:04 am
Location: Edinburgh, Scotland

Re: issue-#100 Review all the existing documentation

Post by Robert »

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
Ivan Denisov
Posts: 1700
Joined: Tue Sep 17, 2013 12:21 am
Location: Russia

Re: issue-#100 Review all the existing documentation

Post by Ivan Denisov »

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.
Zinn
Posts: 476
Joined: Tue Mar 25, 2014 5:56 pm
Location: Frankfurt am Main
Contact:

Re: issue-#100 Review all the existing documentation

Post by Zinn »

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
Ivan Denisov
Posts: 1700
Joined: Tue Sep 17, 2013 12:21 am
Location: Russia

Re: issue-#100 Review all the existing documentation

Post by Ivan Denisov »

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?
User avatar
Josef Templ
Posts: 2047
Joined: Tue Sep 17, 2013 6:50 am

Re: issue-#100 Review all the existing documentation

Post by Josef Templ »

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
Post Reply