Suggestions for documentation improvement

[twindus]

On a relatively quick read up to and NOT including the "Language Features" section: here are some notes on things that could be improved in the documentation from an "outsider" point of view (Note that I didn't test anything myself, just read through it):

On the landing page:

• [x] There isn't really a description of what CMakePPLang is and why it is needed. It is sort of there, but I would make it the first thing that is discussed. Is there a use case outside of CMakePP that you could use as another example of why it is useful?
• [x] It would be useful to provide a link for the CMake Packaging Project.
• [x] The copyright on the bottom of the pages are set at 2019.
• [x] #85

On the getting started page:

• [x] Make a link to CMake and/or useful CMake tutorials.

On the obtaining_cmakepplang.html page:

• [x] I would remove the word "to" in front of the links in the first two paragraphs.
• [x] I assume that in the cmake/get_cmakepp_lang.cmake, the cmake directory is at the top level of the user's project?
• [x] In the "Downloading CMakePPLang and Building Manually" section, I might suggest just reproducing the steps for setting up the project instead of referring back to the previous section. Explicit step by step instructions can be more useful to users (especially if there is any chance that they can be confused!).

I really liked the examples! In getting_started/cmakepp_examples/classes.html:

• [x] For the "Adding a Function That References Attributes", I suggest changing "store them in the current scope with the prefix" to "store them in the current, local scope with the prefix".
• [ ] In 1.6, it might be useful to point out that you are not using the PARENT_SCOPE method from 1.5 and why. I think that would clarify the different ways of returning information.
• [x] In the title "Adding a User-Defined Constructors", I would either delete the "a" or make "Constructors" singular ("Constructor"). This is also the first section without an explicit example like the others. I think this is fine, but it was noticable.
• [x] In section 1.9, maybe point to some definition of KWARGS Constructor? It seems pretty obvious, but if there are newbies out there....
• [x] As I was reading through these great examples, it seemed to me that there should be something at the beginning of this or on the main landing page that emphasizes the C++ like nature of the language.

In getting_started/example_project.html:

• [x] I am not sure why "Greeter(hello" isn't "Greeter(hello ...)" (closing the parenthesis). I think the purpose is to show that there is more to the function, but why not put in the dots. If nothing else, you should probably define what you mean by something without a closed parenthesis. (This shows up in a couple of other places.)
• [x] In the "Defining the Class", you should be explicit about what file the code goes into - someone will ask.
• [x] In the "Building the Project", I am guessing that "nix" should be "Unix or Linux". I would be explicit instead of using the .
• [x] In the "Building the Project" directions, I was a bit confused about what directory the build command should be run at. The first sentence says go to the project directory, which I assume is the "." in the layout picture at the top of the page. Then below the build commands it says that the "." is the root directory for the CMakePPLang repository. Maybe these two are the same? It might be useful to show the layout picture after CMakePPLang has been installed? What am I missing?

[zachcran]

@twindus Thank you so much for the feedback! I will get working on these.

[zachcran]

In 1.6, it might be useful to point out that you are not using the PARENT_SCOPE method from 1.5 and why. I think that would clarify the different ways of returning information.

This is a TODO for me: On rewrite, I noticed that using the PARENT_SCOPE method vs cpp_return() here does not actually make the code more concise, so it is not a good example. I have definitely had times where cpp_return() is more concise than the PARENT_SCOPE method and it also feels more like other languages where you would say return <value>.

• [ ] Rewrite example to actually showcase benefits of cpp_return().

[zachcran]

In the "Building the Project" directions, I was a bit confused about what directory the build command should be run at. The first sentence says go to the project directory, which I assume is the "." in the layout picture at the top of the page. Then below the build commands it says that the "." is the root directory for the CMakePPLang repository. Maybe these two are the same? It might be useful to show the layout picture after CMakePPLang has been installed? What am I missing?

This one was just a typo on my part. I fixed it. All of those references should have been to the example project, not CMakePPLang.

[zachcran]

The copyright on the bottom of the pages are set at 2019.

@ryanmrichard Should this be updated to 2023?

[zachcran]

Perhaps add a list of developers?

@ryanmrichard @twindus I think that along with a list of developers, some contributing instructions would also be useful. The contributing instructions can tell new contributors how to add their names to the list (if we can't find an action to do it for us). I'll make a separate PR from the rest of the edits for this.

[ryanmrichard]

@zachcran contributing instructions are set organization-wide by having a CONTRIBUTING.md file in the https://github.com/CMakePP/.github repo.

When you open a PR, GitHub automatically links to it (see the bottom right corner of the screen shot)

That said, it would be great if GitHub did a better job of showcasing it. In lieu of that, I'd recommend linking back to the one in the .github repo.

The list of developers is a good idea. It would be good to automate at least some part of it (and eventually steal that automation for the NWX org too...).

[ryanmrichard]

The copyright on the bottom of the pages are set at 2019.

@ryanmrichard Should this be updated to 2023?

I thought the copyright year was supposed to be the year it was first copyrighted, but I don't know for sure.

[ryanmrichard]

FWIW this suggests you add a year to the copyright anytime the source is changed.

[twindus]

That is my experience as well.

[zachcran]

FWIW this suggests you add a year to the copyright anytime the source is changed.

Sounds good. I think we missed a few years of updating that then. I'll check which years have had changes (if that is easy to do) and list those years. Likely it will be 2019-2023.