issue-#100 Review all the existing documentation

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 »

Ivan Denisov wrote:I made this changes in P-S-I:
I have looked at PSI (Version 450) and these changes seem good.

The title "Using COM without ..." could be confusing to someone new to BlackBox. How about adding, at the end of the first paragraph:
(Historical note: The Direct-To-COM compiler was supplied as a separate product to BlackBox. It is now fully integrated into the standard BlackBox distribution.)
In fact I wonder if there is any reason to have this section at all. It made sense when people wanted to use COM very occasionally, but did not want to pay for the add-on compiler. Does it make any sense now?

Also: Open Docu/Tut-1, Search for "COM", Delete word "optional" on the next line.
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 »

The changes to the Docu & Mod files for UTC functions are good.
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 »

Why can't the link behavior problems be fixed?
Underlining when moving over a link is the current standard and we are
close to it. So why are we giving it up without trying a bit harder?

- Josef
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 »

Josef Templ wrote:Why can't the link behavior problems be fixed?
Underlining when moving over a link is the current standard and we are
close to it. So why are we giving it up without trying a bit harder?
I fill that I can't solve this issue for reasonable time. I made quiet interesting prototype, however I reached the boundary of my knowledge sphere of BlackBox understanding...
I do not understand why caret is blinking. I even have no ideas why sometimes kinks not work from the first click.
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 »

This issue is classified as 'Support' but it should be 'Bug'.

Why?
'Support' has been used so far for internal stuff like the build engine or other things
that do not appear in the distribution.
The reviewed docu is part of the distribution and therefore has to be
either Feature or Bug. Since it mainly fixes bugs in the docu I would prefer Bug over Feature.

- Josef
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 »

I can't remember if this has been discussed before ...

In Stores the "X" routines have the line "This procedure is provided to simplify migration from Release 1.2 to 1.3."
Of interest to the historians, but should be deleted.

Also what about the "backward compatibility ... this may change" comments on Internalize & Externalize? I think we should correctly document these routines as they are today, and remove speculation about future changes that no one is planning.
Last edited by Robert on Thu Mar 17, 2016 10:30 am, edited 1 time in total.
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 »

Josef Templ wrote:This issue is classified as 'Support' but it should be 'Bug'.

Why?
'Support' has been used so far for internal stuff like the build engine or other things
that do not appear in the distribution.
The reviewed docu is part of the distribution and therefore has to be
either Feature or Bug. Since it mainly fixes bugs in the docu I would prefer Bug over Feature.
I see reasons why we should separate documentation issues from features or bugs. With beta or release candidate we will not be able to add features to BlackBox. However the documentation is possible and even required at this stages. Also documentation issues is not very good to classify as bugs. Because there is some metrics about bugs. BlackBox should not be buggy software. Some typo is not a bug. Bug can crash application or do something unexpected.

So I make two new forums for Documentation and for Infrastructure. I think this will be clear for everybody which kind of issues can be posted there. In Redmine I also changed the classification.
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 »

Ivan Denisov wrote:So I make two new forums for Documentation and for Infrastructure. I think this will be clear for everybody which kind of issues can be posted there. In Redmine I also changed the classification.
I agree.
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 »

Write a substantive Docu for System Log.

If people agree, this would be a separate issue number.

It should be easy, as it is mainly cut-and-paste from StdLog?
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 merged changes from master to this topic branch.

Also I copied parts of StdLog documentation to Log. I do not think, that the separate issue is required. There is no need to hide this documentation in Folds.

The current version for testing:
http://blackboxframework.org/unstable/i ... a1.495.zip

I am suggesting everybody to find the time until weekend to suggest final changes to the Docu and then in the weekend I will try to incorporate the texts in the topic branch.
Post Reply