Hi folks, I am currently working on familiarizing myself with the Avogadro 2 source code, and realized that one of the things that may help future users/developers is a more clear manual for all the things that A2 might have to offer. I have used quite a large number of the features in Avogadro, and considering I somehow let a small amount of free time into my schedule, I figured it would be nice to work on improving some more parts of the manual. The one thing that is really holding me up is that I really am not sure what things should go into the manual and how it should be organized. I was thinking of a basic layout that just subdivides things into the various tabs that they come from, i.e sections for the File tab, Edit, View, Build, etc.
I would love some feedback from y’all, and I would especially like to hear about features of the program that you didn’t know existed or had a hard time to get working for your own use cases. Thanks!
2 Likes
I’m open to suggestions about organization. The way we organized the manual for v1 was to first include basics of each tool and menu, as you describe. And display types - almost forgot that.
Then we moved to slightly more “tutorial” types, like building up different kinds of molecules, materials, etc.
Right now, updating each of the tools and menus would be a big help.
Since I can’t really write C++ it’s the main thing I’ve been doing to try and contribute, but my progress has been less than expected due to my PhD.
I am most of the way through rewriting the tools stuff, so I would say to avoid duplication of effort it might be better to wait to touch the tools section till I’ve finished that, then of course I will be very grateful for your thoughts and input on further improvement. You can see what I’ve done so far here 
The menus definitely need work, especially as the location of different menu options has changed so much. That’d be a good place to start.
The other main thing I did so far was work on redoing the main homepage, which is here.
I’ll open up pull requests for both so that maybe they can be merged. Edit: The PRs are #88 and #89, if you wouldn’t mind taking a look @ghutchis
I also somewhere made a sort of outline of a possible organization scheme for the website, I’ll dig that out. @brockdyer03 if you’re keen to work together on the docs, maybe let’s have a discussion about it some time?
1 Like
I’m keen to work on just about everything that I can to help Av2 become a better program! Let’s connect soon to chat about docs and guides; I’ll throw you a PM!
2 Likes
Something we should definitely expand is the building from source section, and include a list of common problems with solutions collected from the forums, as this is really not easy for newcomers, as you’ve experienced yourself!
With Geoff having answered so many questions here over the years, some of which come up time and time again, I think an FAQ section of the documentation would be a good idea too. A prime example off the top of my head being “Why can’t I see X extension?” with the solution generally being to install Python.
If you want to add a FAQ to the building from source, that sounds like a good idea. Similarly, a FAQ for the general documentation sounds good.
If someone wants to start adding questions, I’m happy to add the answers.