MantisBT
Mantis Bug Tracker Workflow

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0027191Community[OCCT] OCCT:Documentationpublic2016-02-19 14:152017-08-28 19:30
Reporterjma 
Assigned Toabv 
PrioritynormalSeverityintegration request 
StatusfeedbackResolutionopen 
PlatformOSOS Version
Product Version 
Target Version[OCCT] 7.4.0*Fixed in Version 
Summary0027191: Documentation - redesign of information architecture
DescriptionThe attached OCCT_user_experience.pdf doc is an overview of current state of OCCT documentation. It highlights the articles drawbacks and information organization weaknesses.

In scope of this issue it is proposed to redesign the documentation structure ruling by the ideas from the mentioned pdf. The draft skeleton is in OCCT_documentation_redesign.xlsx.

Besides the redesign itself, the found text misprints/rudiments and obsolete/not-full instructions will be corrected.
TagsNo tags attached.
Test case number
Attached Filespdf file icon OCCT_user_experience.pdf (783,890 bytes) 2016-02-19 14:15
xlsx file icon OCCT_documentation_redesign.xlsx (14,736 bytes) 2016-02-19 14:15

- Relationships

-  Notes
(0055888)
git (administrator)
2016-07-13 17:26

Branch CR27191 has been created by jma.

SHA-1: 051da04dbe916e66a3a914410f7b1c9014c564a4


Detailed log of new commits:

Author: jma
Date: Wed Jul 13 16:53:41 2016 +0300

    0027191: Redesign of information architecture
    
    The documentation architecture was totally redesigned to provide more logical and clear from user's point of view structure. Its current state reflects the general workflow steps using OCCT, what, in its turn, simplifies the process of searching of required info.
    
    Some hige articles were splitted into set of logically independent and comprehensive articles. There was simplification of 'sections' hierarchy too.
    
    Some modifications of articles text were done to eliminate obsolete or redundant info, correct misprints, improve readability and formatting.
    
    Table of content control was significantly improved for better navigation within articles.
(0055913)
abv (manager)
2016-07-14 16:28
edited on: 2016-07-14 16:31

The changes look find in general and the proposed new structure looks quite logical. Still I have a few remarks after first look:

1. On Overview page, please recover licensing information:

a. Reference to LGPL should be a link (the same for exception), and it should lead to document which is part of the same documentation (not link to external web site)

b. Text "See the license text for formal disclaimer." should be put after disclaimer ("...provided on an "AS IS" basis...").

c. It is good point to keep the License as top-level item: for people considering use of a product in serious application this is one of the first things to be checked, thus it should be quite visible.

2. As for me, reversing the order of items in Upgrade guide is poor idea. When a person needs to upgrade his application, he most likely will start not from the last-but-one version, but several versions back. The logical procedure for upgrade is to apply changes in historical order, and not starting from the latest (which may refer to some previous changes). Hence, I believe it will be quite difficult to apply, please consider rolling back.

3. Tutorial can be better separated from samples: these are two different things. Currently Tutorial looks like buried inside the list of samples, and it may be difficult to recognize its existence. I would keep Tutorial as separate top-level item.

(0055932)
kgv (developer)
2016-07-15 11:27

> Build and Upgrade
>  -> Build OCCT
>    -> Cross-Platform Compiling using CMake Tool

This article (originally "Building with CMake for Android") is dedicated for building OCCT for Android (as target) platform.
However, the target platform has been lost from title.

This also means that section Linux
Linux

You may choose one of the following ways to generate, configure and build OCCT sources on Linux just 
keeping in mind this platform specific:

    Configuration, generation and building OCCT on Windows using CMake tool
    Cross-Platform Compiling using CMake Tool

points to the wrong location.

> Build and Upgrade
>  -> Build OCCT
>    -> Cross-Platform Compiling using Code::Blocks

Using "cross-platform" is confusing in title.
"Cross-compiling" term is usually used when Target and Host platforms are different (e.g. when compiling for Android on Windows/Linux using Android NDK, or compiling for Windows on Linux using MinGW).
Related article (originally "Building with Code::Blocks") describes Code::Blocks project files generation intended for building OCCT on the same platform (Windows, Linux, OS X), thus unrelated to "cross-compiling".

> Build and Upgrade
>  -> Upgrade from Older OCCT Versions
>    -> Upgrade to OCCT 7.0.0

Subsections are no more listed in the document structure.
In such big change-log as for OCCT 7.0.0 release, user might be interesting in particular section, but now he have to scroll all changes to find out what is really important for his application.

> Debugging
>  -> Implementation Details: Boolean Operations 

It looks like this chapter has been included into Debugging section by mistake.
(0055936)
jma (developer)
2016-07-15 13:33

@abv

"1. On Overview page, please recover licensing information:"
It seems like that it is not debatable remark and license info must be restored. Nevertheless, imho the official web-site is right place for such "political" things, not technical documentation. Serious guys with serious projects contact to web-resources and contact representatives at first, again -- not to tech documentation.

Each new top-level item scatters the documentation structure and makes the search process harder.


2. As for me, reversing the order of items in Upgrade guide is poor idea.

Yeap, agree, not the best idea.


3. Tutorial can be better separated from samples: these are two different things. Currently Tutorial looks like buried inside the list of samples, and it may be difficult to recognize its existence. I would keep Tutorial as separate top-level item.

I believe that the person looking for the code snippets go straight to Samples section. However, I agree that application-formed "tutorials" and step-by-step tutorials and draw based samples are different things and perhaps, it makes sense to rename section to "Samples and Tutorials" and/or move app-formed samples to a separate item to clarify structure. Keeping Tuto as a separate top-level item is not good idea as it breaks documentation structure without tangible reason. Following this idea, OCAF related samples should be formed as top-level items.
(0055937)
jma (developer)
2016-07-15 13:46

@kgv

-> This article (originally "Building with CMake for Android") is dedicated for building OCCT for Android (as target) platform.
However, the target platform has been lost from title.

Following to the article content this approach is Ok for Win/Linux as well just keeping in mind some platform-specific moments. To not confuse the users and hint them about more existent options "Android" word was removed from the title.

-> Using "cross-platform" is confusing in title.

Yeah, mistake occurs....I'll correct

-> Subsections are no more listed in the document structure.

From my point of view upgrading procedure requires step-by-step following to instructions. That is why, subsections are excess here.

-> It looks like this chapter has been included into Debugging section by mistake.

Nope, it was intention. This section is for whose who is going to debug OCCT -- helpful hints and implementation details to describe architecture/conventions/terminology/etc.
(0055938)
abv (manager)
2016-07-15 13:57

-> From my point of view upgrading procedure requires step-by-step following to instructions.

That is not correct; in practice the user shall be able to parse the document to find easily the points relevant for him. TOC is always useful as it provides top-level view on the subject.
(0055939)
jma (developer)
2016-07-15 14:21

Definitely, however in the current case the relevant points are already reflected by TOC -- source and target OCCT versions. Providing him by subsections on each step means to overload TOC.
(0055940)
abv (manager)
2016-07-15 14:29

Subsections provide list of topics in particular section. It is extremely useful to have it, as it provides idea of what kind of changes are made in given version. Consider that not every one who reads that guide has a task of upgrading existing code and needs to go in depth of all the points, it can be also a person who just needs to get rough idea on what happened.
(0055941)
jma (developer)
2016-07-15 14:35

For that it makes sense to add 'Release Notes' section as Upgrade instructions do not give the whole overview the changes done.


The dispute about having/not having subsections and in what cases can be endless. Regarding 'Upgrade' section it is not critical for me to have subsections.
(0055942)
kgv (developer)
2016-07-15 14:39
edited on: 2016-07-15 14:41

> Following to the article content this approach is Ok for Win/Linux as well just keeping in mind some platform-specific moments.
> To not confuse the users and hint them about more existent options "Android" word was removed from the title.
This article has been _specifically designed_ to point out how OCCT can be built for Android platform.
Since this procedure relies on non-standard CMake toolchain extension it can not be used for any other means.
For building OCCT on standard platforms there is dedicated description.

User would look for "Android" (or "mobile platforms", but we don't have here description for iOS yet) - more specific case, not general "cross-compiling" (which not every developer understands).

> Nope, it was intention. This section is for whose who is going to debug OCCT -- helpful hints and implementation details to describe architecture/conventions/terminology/etc.
From my point of view this article is unrelated to debugging - it is a general overview of Boolean operations with a lot of details.
Understanding the things is good for debugging, but I doubt that debugging is the only purpose for this tremendous article.

(0055943)
jma (developer)
2016-07-15 14:48

-> User would look for "Android" (or "mobile platforms", but we don't have here description for iOS yet) - more specific case, not general "cross-compiling" (which not every developer understands).

Exactly! The user does not llok for how to compile OCCT by specific tool, but target platform. That is why the prev naming is not Ok. How do you like to name it just "Android"?
(0055944)
kgv (developer)
2016-07-15 14:50
edited on: 2016-07-15 14:50

> Regarding 'Upgrade' section it is not critical for me to have subsections.
As a visualization expert, I'm specifically interested in porting changes related to this specific domain.

When I'm porting application to new version from quite old one, I would like to see the actual problems in the document structure - thus removed entities are MORE important for me then OCCT versions.

Of course, common user might follow entire document from version to version, but this does not cover all scenarios.
The change makes also impossible referring to specific sections in communication channels due to missing "anchors".

(0055945)
kgv (developer)
2016-07-15 14:53

> How do you like to name it just "Android"?
Taking into account that other chapters are called "Windows", "Linux" and "Mac OS X" - the "Android" sounds consistent in this list.
(0055946)
jma (developer)
2016-07-15 15:00

-> Of course, common user might follow entire document from version to version, but this does not cover all scenarios.

Trying to cover all scenarios very often lead to mess into interaction. But again, here is not a case, let's move them back.

-> The change makes also impossible referring to specific sections in communication channels due to missing "anchors".

To anchor you are free to use \anchor keyword, it is more suitable for that than (sub)sections.


(0055947)
abv (manager)
2016-07-15 15:13

On license: it must be included with the product unconditionally, otherwise the package is incomplete. Reference to license published on web site may not be appropriate, as it may change or disappear at any moment. For instance, OCCT 6.5.0 has OCCT PL license, while current OCCT versions have LGPL.

On tutorial: I believe it is more useful than all samples (which are of poor quality now), hence deserves to be on the same level at least.
(0055948)
jma (developer)
2016-07-15 15:25

How can we keep the logical doc structure if we place items by "quality" criteria...
(0055957)
ssv (developer)
2016-07-15 16:00

Why not invite the community to this discussion? They use this documentation and they need it more than us for sure. My personal opinion is that

a) the article on Booleans is USELESS for everybody except few folks here. Has anybody ever tried to read it?

b) playing with samples (whatever quality they are) is much more fun and interesting that reading some tutorial on modeling. Most of the people want to see what OpenCascade can do before their start doing something by hands. Many of those who will start will never do any modeling, and this tutorial is, again, useless for them. Especially, since we have all this in Draw as Tcl scripts.

c) It is a common practice (e.g. see PCL lib) to collect many tutorials together. Today we have only one, but we can foresee that others will appear in future. And we can encourage community to write some (again, example of PCL proves that it works).
(0058398)
git (administrator)
2016-10-04 15:02

Branch CR27191 has been updated forcibly by jma.

SHA-1: 1438a1fb3513b8cecfde3541143e3044d17fba19
(0058400)
jma (developer)
2016-10-04 15:31

The following remarks were taken into account:

from abv:

"1. On Overview page, please recover licensing information:"
"2. As for me, reversing the order of items in Upgrade guide is poor idea."

from kgv:

"Subsections are no more listed in the document structure."
"Cross-Platform Compiling using Code::Blocks is confusing in title."
"This article ... is dedicated for building OCCT for Android..."
(0059237)
git (administrator)
2016-10-27 11:36

Branch CR27191 has been updated by jma.

SHA-1: e4f54960657343bad2412c83406f02e0d356dec2


Detailed log of new commits:

Author: jma
Date: Thu Oct 27 11:35:20 2016 +0300

    eliminate numbering in files headers

(0059286)
abv (manager)
2016-10-27 17:11

Please rebase on current master -- there are conflicts in renamed files
(0059904)
git (administrator)
2016-11-05 17:09

Branch CR27191 has been updated forcibly by jma.

SHA-1: f6ca21b7d553043d9909feb1c013f5269f82f779
(0059905)
jma (developer)
2016-11-05 17:18

Seems to be successfully rebased ... but I'm not sure because of git's "friendliness".

If any troubles please reassign back to me.
(0060652)
abv (manager)
2016-11-22 10:03

I had problems rebasing this commit on corresponding master (conflicts) + multiple Doxygen errors and warnings. Since a number of other changes in files renamed in this patch are coming to version 7.1.0, this patch is shifted to 7.2.0 to avoid need of manual merging each of these changes.

In addition, separation of user guides into parts breaks current practice of generating one PDF per user guide. This has to be discussed.

The structure of documentation is to be revised; for instance, having description of BOP algorithms in section "Debugging" is completely unnatural.

- Issue History
Date Modified Username Field Change
2016-02-19 14:15 jma New Issue
2016-02-19 14:15 jma Assigned To => bugmaster
2016-02-19 14:15 jma File Added: OCCT_user_experience.pdf
2016-02-19 14:15 jma File Added: OCCT_documentation_redesign.xlsx
2016-06-20 12:43 jma Assigned To bugmaster => jma
2016-06-20 12:44 jma Severity minor => feature
2016-06-20 12:44 jma Status new => assigned
2016-06-20 12:44 jma Target Version => Unscheduled
2016-06-20 12:57 abv Target Version Unscheduled => 7.1.0
2016-07-13 17:26 git Note Added: 0055888
2016-07-13 17:30 jma Status assigned => resolved
2016-07-14 16:28 abv Note Added: 0055913
2016-07-14 16:31 abv Note Edited: 0055913 View Revisions
2016-07-15 11:27 kgv Note Added: 0055932
2016-07-15 11:27 kgv Severity feature => integration request
2016-07-15 11:27 kgv Summary Redesign of information architecture => Documentation - redesign of information architecture
2016-07-15 13:33 jma Note Added: 0055936
2016-07-15 13:46 jma Note Added: 0055937
2016-07-15 13:57 abv Note Added: 0055938
2016-07-15 14:21 jma Note Added: 0055939
2016-07-15 14:29 abv Note Added: 0055940
2016-07-15 14:35 jma Note Added: 0055941
2016-07-15 14:39 kgv Note Added: 0055942
2016-07-15 14:40 kgv Note Edited: 0055942 View Revisions
2016-07-15 14:40 kgv Note Edited: 0055942 View Revisions
2016-07-15 14:41 kgv Note Edited: 0055942 View Revisions
2016-07-15 14:41 kgv Note Edited: 0055942 View Revisions
2016-07-15 14:48 jma Note Added: 0055943
2016-07-15 14:50 kgv Note Added: 0055944
2016-07-15 14:50 kgv Note Edited: 0055944 View Revisions
2016-07-15 14:53 kgv Note Added: 0055945
2016-07-15 15:00 jma Note Added: 0055946
2016-07-15 15:13 abv Note Added: 0055947
2016-07-15 15:25 jma Note Added: 0055948
2016-07-15 16:00 ssv Note Added: 0055957
2016-10-04 15:02 git Note Added: 0058398
2016-10-04 15:31 jma Note Added: 0058400
2016-10-07 18:15 jma Assigned To jma => abv
2016-10-27 11:36 git Note Added: 0059237
2016-10-27 17:11 abv Note Added: 0059286
2016-10-27 17:11 abv Assigned To abv => jma
2016-10-27 17:11 abv Status resolved => feedback
2016-11-05 17:09 git Note Added: 0059904
2016-11-05 17:18 jma Note Added: 0059905
2016-11-05 17:18 jma Assigned To jma => abv
2016-11-22 10:03 abv Note Added: 0060652
2016-11-22 10:03 abv Target Version 7.1.0 => 7.2.0
2017-08-28 19:30 abv Target Version 7.2.0 => 7.4.0*


Copyright © 2000 - 2018 MantisBT Team
Powered by Mantis Bugtracker