Documentation Overhaul, perspective of a new user

[john01dav]

I just came across this library and it looks like the features are great, but, unfortunately, actually using it is an extremely frustrating experience. First, just to get it to work in my project (via add_submodule), I had to dive into code and debug it myself, mostly by trial and error, to determine that I must state LANGUAGES CXX in my project() call in my root CMakeLists.txt (without this I get a cryptic error about header files). This took about an hour, just to link the library, and it could have been much quicker if there was some clear and obvious documentation about how to do this.

Then, once I finally get it building, I needed to dig all over the place to find any documentation on how to use it. When I finally find something, it talks about including a header that doesn't exist (this page says to include <nana/gui/wvl.hpp>, but this header does not exist based on how I finally got it linking, which, of course, could also be the problem, but in either case, the documentation is the problem). Additionally, this documentation is in a repository on someone else's Github in a fork (who seems to be a major contributor based on how much I saw them commenting on the issue reports I looked at to get it building), which is a strange place for it, as opposed to, for example, in the wiki tab of the repository that it documents.

Lastly, there is a website (nanapro.org), but it is utterly unclear to me how it fits in with the various github projects and forks.

I think that these actionable changes would massively improve the experience of a new user, and probably make things cleaner for regulars too:

• Move all repositories for the project into an actual Github organization, and put clear, big, red, obvious, impossible to miss messages on all the other repositories. A good way to do this is to remove all files in these repositories with one last commit, and add a README.md that expalins where everything moved and gives a useful link or two (one for the organization and one for that particular project's new location would be good). This ensures that everything is in one place, it's clear what's officially part of the project and what isn't, and that everyone who currently goes to the current project can easily find where people moved to.
• Make sure that all documentation is in one official-looking place, or, at least, all documentation of the same type (e.g. one place for reference documentation, another for tutorials). Good candidates for the tutorials are the Github wiki on the main repository, or on a separate repository in the aforementioned organization. This is currently an issue because it seems like the documentation is spread around various github repositories, some of which are no longer maintained, and on the website in various places.
• Have all the links that a user may need in order to get started with the project in README.md. A good way to do this is to have a section titled "Documentation" or "Getting Started" that links to the main documentation area, and, ideally, a few specific tutorials (e.g. "Hello World" and "Installation/Linking")
• Have an explicit tutorial for how to link. Such a tutorial would not need to be very long at all (1-3 paragraphs would be plenty), because once I figured it out, linking isn't actually that hard, but there are a few pitfalls that take a long time to figure out unless someone tells you. I might be willing to write such a tutorial for Linux+Cmake.

[qPCR4vir]

Hi, thank for your time! In the readme you have just only one link to the documentation:

Support The best way to get help with Nana library is by visiting http://nanapro.org/help.htm

(for many users GitHub is not the entry site, and many don't even like to use it!). The first thing you have in http://nanapro.org/help.htm is the list of links you want.

A GitHub organization sound like a good idea, but it is some amount of work to create and organize... specially because in real life there is not such organization.

Where did you found <nana/gui/wvl.hpp>? The main problem with a wiki is that is not updated automatically. For an automatic documentation see the "Programmer Guide and Examples"

[qPCR4vir]

Hi!

I just created a new simple GitHub demo project:

https://github.com/qPCR4vir/nana_helloworld

I hope it will help

[jimorc]

First of all, I am new to nana, and I agree that having a single, official source for nana documentation would be useful.

qPCR4vir - I think this is a great start. Another topic, probably in getting started, is how to get and build/use nana. For example, in your nana-helloworld example on GitHub, you simply copied the source code manually from GitHub to a subdirectory in your project. This could be done automatically using CMake, as I show in Creating a nana based project using CMake. nana is also available using vcpkg.

There seem to be special instructions for each IDE; these could/should be included as well. I am not sure if these can be included in the CMakeLists.txt files. If not, then they should be documented as well.

I would be willing to help provide this documentation. However, I will do so only in official documentation. At the moment, qPCR4vir's documentation is the best I have seen, but it just adds another unofficial documentation source.

What is the status of this? Don't others see this as a good idea? What needs to be done to move this to nanapro.org?