Announcement for the dev docs and unifying the sections of the docs.

[Revathyvenugopal162]

In favor of the ongoing modification on multi-doc in the documentation of our projects, Following are the modification proposed for the docs.

1. Add a developer announcement for the documentation in the same way as depreciation warning for older version. Example https://mapdl.docs.pyansys.com/release/0.62/
2. Uniform sections for all documentation. (Getting started, User Guide, API etc..). Keeping the contribution in only one repo(probably in dev.docs.pyansys.com) and link to that by an icon. (like dark/light mode button on the right corner of the docs)
3. Add an icon in documentation to download the pdf version.
   Pinging here @pyansys/pyansys-core and @pyansys/documentation for further discussion.

[PipKat]

@Revathyvenugopal162 , Would you please clarify this statement in point 2: Keeping the contribution in only one repo(probably in dev.docs.pyansys.com) and link to that by an icon. Thanks!

[Revathyvenugopal162]

Yeah sure. Instead of having a section called contribution, we can keep an icon for that, as seen in the screenshot attached. And for most of the cases we can keep that icon linking to a common page. (It will take us the contribution page in pyansys dev guide.)

[germa89]

The pyansys dev guide is quite general, whereas some projects might have some specific information about how to contribute. I think that button (in my opinion, very small) should point to a section/chapter in the documentation. In that text, we can then reference the pyansys dev doc.

[PipKat]

I agree with German. Several libraries have a Contribute topic with information that is unique to their respective repos/setup. The Contribute topic then links to the general Contribute topic in the PyAnsys Developer's Guide for general guidelines. I also have no include what the icon is supposed to be! It looks like a gavel! It doesn't seem intuitive at all.

[germa89]

[germa89]

Regarding:

Uniform sections for all documentation.

Which sections are going to be?

I presume it will be:

• Getting started
• User guide
• MAPDL commands
• Examples

Then where we should put the following?

• Learning PyMAPDL
• Troubleshooting
• Contributing and API

I would like these sections to have enough visibility.

Pinging @Revathyvenugopal162 @jorgepiloto @PipKat for visibility.

[germa89]

(In this case, it might be better located in the "User guide" section rather than the "Getting started" section though. (We could reference it in an FAQ asking "Where do you find information on resolving common issues?" or something like that.

I like the idea of referencing troubleshooting in the FAQ section.

I think this should be detailed in the dev guide, and we should also be consistent with where this sections are (FAQ, and Troubleshoot included). For PyMAPDL I feel they belong to Getting started, but I will go with the general common sense we can get from this discussion.

So, where Troubleshoot and FAQ should be? In Getting started or User guide ??

[germa89]

Additionally, we should include this structure in the ansys-template package.

[germa89]

Interesting case is also Contribution, @akaszynski mentioned he would like it to be as an icon. I also think it should be searchable through the previous defined structure.

I believe the API is more about developers, so it is about contributing. That is why I merged API with Contributing in PyMAPDL. But this seems a bit confusing for some people.
Then I would propose to link Contribution in Getting Started, and also at the top right icon (we should change the icon though).

[PipKat]

@germa89 Tom Johnson is a highly respected blogger on technical writing. In the following post, he makes some excellent points about where troubleshooting sections (which really provide answers to FAQs) should go:
https://idratherbewriting.com/2010/07/08/separating-basic-from-advanced-topics-how-twitter-organizes-their-help-organizing-content-18/

I think it would be cool if we create some type of directive with a cool icon for a Troubleshooting subsection and then put it within the relevant topic, as suggested by Kathy Sierra in this post from several years ago: The best user manuals EVER.

[germa89]

I'm going (for the moment) with this:

As detailed in ansys/pymapdl#1689

Tom Johnson is proposing to split troubleshooting across the documentation, so it is easy to find it. I do not like much that. I understand the point though.
I rather have links inside the documentation to the troubleshoot section.

[germa89]

I'm going to detail my proposal for documentation structure:

• Getting started
  • Learning
  • Frequency Asked Questions
  • Contribute
• User guide
  • Troubleshooting
• MAPDL commands
• API reference
• Examples

[germa89]

I'm pushing this scheme in PyMAPDL. We can adjust it later.

ansys/pymapdl#1689

[germa89]

For your info, the following projects have the next structure:

Numpy

Link: https://numpy.org/doc/1.23/

• User Guide
• API reference
• Development
• Release notes
• Learn

Pandas

Link: https://pandas.pydata.org/docs/

• Getting started
• User Guide
• API reference
• Development
• Release notes

Pyvista

Link: https://docs.pyvista.org/

• Getting Started
• User Guide
• Examples
• API Reference
• Extras

Surprisingly all of them have a Development tab which talk about contributing, guidelines, benchmarking, etc
Numpy dev page is https://numpy.org/doc/1.23/dev/index.html

Maybe we should consider to something like this too. The icon might be a bit to hidden.

I dont like the release notes on the main though.

[germa89]

Furthermore... I believe we can change the link of the contribution button using one of these:

https://fontawesome.com/v4/icons/

I have selected the following:

• https://fontawesome.com/v4/icon/wrench [My preferred]
• https://fontawesome.com/v4/icon/pencil
• https://fontawesome.com/v4/icon/code
• https://fontawesome.com/v4/icon/terminal
• https://fontawesome.com/v4/icon/star
• https://fontawesome.com/v4/icon/heart
• https://fontawesome.com/v4/icon/files-o
• https://fontawesome.com/v4/icon/cogs
• https://fontawesome.com/v4/icon/cog

[germa89]

Also, because of how the icons are set in the conf.py

....
{
            "name": "Contribute",
            "url": "https://mapdl.docs.pyansys.com/release/dev/getting_started/contribution.html",
            "icon": "fa fa-wrench",
        },
...

We need to use the explicit hard link... Hence I would propose to use the dev version so we don't need to change it accordingly to the version.

[germa89]

Pinging @Revathyvenugopal162 @jorgepiloto for feedback on this.

[germa89]

I think we could hack it to point to the Contribution in latest stable... but I dont think it is a big deal.