ansys/pydpf-core

Review PyDPF current documentation

Closed this issue · 0 comments

luisaFelixSalles commented

Review and comment the existing website documentation

General observations

  • SO confusing, Its pretty easy to get lost in the site and pretty hard to get to the info I'm looking or. Where should I go??? idk
  • The first page (when we click in the logo PyDPF) is confusing. The same thing is said in four different paragraphs with different words. That means that a lot is said but its content is quite vain
  • The word "entity" is used to many times to define several things. its confusing

Website sections

  • Getting started
  • When we click on 'Getting Started' we go to a page where the first thing to do is installing the DPF server. However the navigation section suggest that this should be done after installing PyDPF-core

Image

  • The first page suggests that to use PyDPF-Core we always have to start by creating a model, when this section goal was to show how to test the installation
  • installation: maybe be more specific like specify a pyton environment/ were?/ maybe some figures?
  • DPF server:
  • Compatibility; ok
  • Licensing: ok
  • Dependencies: ok
  • User guide
  • I think that starting with "Describe the most-used DPF entities " is not so logical. When we go to an user guide we expect to find a enumerate catalog that give us the guidelines to start/ how to use DPF starting with the "must to" basics. like: 1- get a result file -> 2- get the data from it -> 3- create a model ...
  • Operators : this part explain how to use and chain operators with different methods. We should have this in a core example because getting to this page is not that easy // The section "create an operator " doesn't shows how to create an operator
  • Plot: it just shows how to plot a model as it was defined with the results file

  • API reference
    List of found issues:

  • #1693

  • #1698
    -' .material_support_provider() ' works? no, why it is here
    -'mesh_support_provider()' works? no, why it is here

  • 'MeshInfo' : Explain that this works only for cfx files and lsdyna files

  • The 'cos' operator: specify that the angle is in radians

  • We would say this page is empty:

Image

  • Why this is different:

Image

Image

the fact that we can't read the complete name is annoying

  • We don't have information about the pins in each operator. So if i need to know it i will be forced to cross information with the operators webpage
  • The class/ function names are different in this page and in the operators page. If i need to do what i said in the last topic i will be lost and confused (I noticed this when i needed to consult the split_mesh class)
  • Common section? what does it really have
  • Operators
  • Just send us to the[ operators documentation. It doesn't explains what we will find there.
  • The examples given for each operators aren't real examples
  • A lot of operators don't have the inputs explained
  • The description is for someone interested in coding, it does not inform us the concrete utility of the operator
  • Finding/ researching the operator that correspond to our needs is pretty hard, almost impossible
  • If I need a operator and it is not used in one of the examples in the examples page I really don't know how to find/search for the operator i need
  • The example of usage in the results part show call for all the operators:

Image

when the usual usage would be with "results " in plural. When we use that? i cant find the 'ansys.dpf.result.' package - Just found it in the api section -> almost impossible

  • Concepts
    Comments
  • Why this part is so hidden?? it should be one of the firsts things we see
    List of found issues:
  1. Terms and concepts
  • The field explanation is too short. like what are the entities in a field? what size they can have? dimension? it can be a matrix? vector?
  1. DPF capabilities and scripting language
  • the firsts things explained here are not what a user will be looking for. It would be more useful to have the "DPF integration" part in the beginning where we explain where and for what we can use dpf (example: "Use it to perform custom postprocessing and visualization of results directly within the Mechanical application" )
  1. DPF usage