📚 Docs improvements Tracker

[tylerflex]

Some of these are a bit ambiguous, maybe you can split them up amongst yourselves depending on how it makes sense to handle it?

• Old documentation in website causing errors (links?) #1433
• Difficult going back and forth from API reference to examples in docs. #1434
• Needs more info about what equations are running in background. #1435
• Explain datastructures better. #1436
• Better document setting BCs automatically #1437
• Document / FAQ on what user should to do if notebook crashes in the middle of a session. #1438
• Every document should follow a consistent naming method (?) #1439
• More info on limitations of tools (eg. Adjoint doesn’t support dispersive) #1440

[tomflexcompute]

Thanks @tylerflex for organizing the user feedback. In one incident just yesterday, a user tried to define a Near2FarAngleMonitor but apparently got a validation error. Somehow he referenced the 1.6.3 docs but was using tidy3d 2.5.0. Just wondering if we do want to keep all the docs versions available. As time goes on we will have many many versions of docs and the older ones are obsolete. Maybe we should remove them anyway as the solver doesn't support them either.

[tylerflex]

sounds good to me. maybe we can support >=2.0 for the time being. Feel free to append to the original list above.

[e-g-melo]

These user feedbacks are very useful! It reminds me that besides content creation, we should constantly improve our web interfaces, so users can easily find what they need.

This comment is very interesting: "Difficult going back and forth from API reference to examples in docs". Maybe we could include a floating panel to show object definitions in our examples within the learning center. So when the user clicks an object link, we show a sidebar floating panel instead of opening a new browser tab.

Another point would be improving the interconnection between the learning center and documentation. Could we have the documentation within the marketing website? Is that a crazy idea? :)

[daquinteroflex]

So some of these issues might get solved by the tasks within the improve docs issues #1148, flexcompute/tidy3d-notebooks#18 which I have pending.

I agree with Tom's suggestion on the versioning too!

This comment is very interesting: "Difficult going back and forth from API reference to examples in docs". Maybe we could include a floating panel to show object definitions in our examples within the learning center. So when the user clicks an object link, we show a sidebar floating panel instead of opening a new browser tab.

This would be really interesting. It'd be good to explore this further. I had thought having the API fully linked within the notebooks would have helped in going back and forth between them. I had done this in my original notebooks refactor which I had to throwaway those commits to get them to build properly, but maybe I need to explore migrating that back in.

In 2.6 there should be more links to examples within the API reference too, however, I agree it can be better. I had the intention to write standalone examples for each class which I thought would also be interesting to explain the usage. We could extract the relevant API data in order to put it as pop up object definitions like you suggest, it'd be interesting to explore how that looks like specifically.

Just writing down a few more thoughts on top of the pending issues related to this too:

• Old documentation in website causing errors (links?) [users were looking at 2.6 docs, and specifically the design plugin, maybe there are some links to old docs in there?]

Yes, I think Tom raised this issue. I will be improving a lot about this very soon which hopefully irons out the wrong links.

• Full review of notebook links again I need to do. I will port the review I did previously that I had to ignore when the notebooks build failed in rc1.

• As part of the multiphysics data structures, I am exploring the implemented equations in terms of the data structures and intend to improve the reference docs from that too. So maybe this kills a few issues in one appraoch. But we can just solve issues as we find them and I'll be working on this from my angle too.

[tylerflex]

Tom noticed some extra methods, see TPA

https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.TwoPhotonAbsorption.html

("Methods" section)

Is this a rendering issue?

[daquinteroflex]

So they are there so we can add extra documentation onto the parameters like the ones in the Simulation API https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.Simulation.html#tidy3d.Simulation.grid_spec

Will be doing progressive improvements to the actual content but we're in a position it's much easier to do now!