Help Needed - User Documentation 2.0

General Discussion
1

While the 1.9x series is still in active development, we’d really like to have some nice user documentation for the 2.0 release.

This would also include:

  • Screenshots (on multiple platforms)
  • Tutorial videos / walk-throughs
  • Editing
  • Possible language translation if that interests you.

While some things have changed substantially, some parts of the documentation just need some minor edits and new screenshots.

Also, to quote @mhanwell from the push for v1.0:

It would also be great to hear what forms of documentation people find
most valuable, what features you feel need the most documentation.

In short, we’re looking for some help generating screenshots, examples, tutorials and the like.

We’d also like your thoughts on features that are poorly documented or tasks you’d like to know how to perform in Avogadro 2.0.

I’m cooking up some swag, so I can promise goodies as a means to thank everyone.

1 Like
2

Hi ghutchis,

Bumping this thread because it seems to be only one specific to documentation.

I’m very keen to get involved with the project and help it along to the 2.0 release. Unfortunately I don’t know C++ so contributing to or even really understanding the code is beyond me. I have already translated as much to German on weblate as I am able to.

Given how frequently you have spoken of the need for documentation and screenshots for v2.0, it seems like this is the most pressing issue for the project. I would be very happy to make myself useful and put some hours into this.

I have looked through the repos and this forum as best I can but can’t find where the docs for 2.0 are hosted, only those for 1.2 (Source for current Avogadro documentation - #2 by ghutchis). Is there an existing github repo I can start looking through and contributing to?

If not, should we make one? As an amateur in comp chem I very much like the format adopted by xtb and orca using readthedocs.io and based on ORCA tutorials - Compatible with ORCA 5.0! — ORCA tutorials 5.0 documentation it seems like it would be possible to use readthedocs but host it within the two.avogadro.cc website.

1 Like
3

The two.avogadro.cc website uses Sphinx, so yes you could use RST. In general, I’m using Markdown / MyST instead of RST because the previous documentation is already in Markdown and there are generally more tools to process it. The build process is essentially the same.

The manual is on GitHub, e.g. manual/major-new-features.md at rev-2.0 · Avogadro/manual · GitHub - just on a different branch.

In general, I’ve been using GitBook to edit the docs – it’s a great interface. But I need them to re-authorize our “open source team” account before adding new users.

In the meantime, I’d certainly appreciate screenshots or edits to the rev-2.0 branch of the manual. For example, help on the intro tutorial would be great.

4

Okay, we’re good to go. If you’d like to help with documentation, please send me a message and I can add you on GitBook.