Proper Documentation

[colin-marshall]

I think FoundationPress is at a point where we should move away from using README for documentation and have a dedicated site/page for it.

Here are some ideas:

1. We could include it in the FoundationPress demo site, but that might be difficult for others to contribute to it.
2. We could use GitHub pages so people can contribute and it gets a dedicated URL. It would probably require us to use a separate repo for the docs.
3. We could use this repo's GitHub wiki. They're not my favorite, but they allow for easy collaboration and it's contained within the repo.

Anybody have other ideas of their own, or opinions on the options listed above?

[olefredrik]

If there is a need for more documentation, I suggest that we put it in a Github Wiki in this repository. A documentation summary, such as procedures for installation should still be available in the README.

Either way, it's fully possible for anyone to contribute documentation today in the README using pull requests. But I see that it is not ideal with a lot of unstructured content if we get a critical amount of information.

[dantahoua]

Yeah at least a small doc would be interesting, at least historical... Just for example, now to start compile we have to type "npm start"... I was used to type "npm run watch" for more than one year. Would be great to know what to use regarding each version... Sometimes you have to dig in an older project and you have to find the right command! Also I just discover by installing the new version that there is no more "custom" folder for "js" and no more "npm run package"... The package option with the generated zip was very helpfull and time saver!!

[colin-marshall]

@dantahoua as mentioned in #1090, the package script was removed because it was causing problems. I will revisit once I find out more about the problems.

@olefredrik can you please point me to the issues related to the package script that were causing problems and made you decide to remove it? I tried searching and couldn't find it. Thanks!

[dantahoua]

Great! And I forgot to congrats you two for this amazing work! :)

[olefredrik]

@colin-marshall I answered your package script question in this thread https://github.com/olefredrik/FoundationPress/issues/1090

[Aetles]

Anybody have other ideas of their own, or opinions on the options listed above?

I think part of proper documentation would be to always have proper commit messages for every single commit. No pull request should be accepted unless it has a proper commit message.

The Tower documentation has some good advice regarding version control best practices:

5. Write Good Commit Messages Begin your message with a short summary of your changes (up to 50 characters as a guideline). Separate it from the following body by including a blank line. The body of your message should provide detailed answers to the following questions: What was the motivation for the change? How does it differ from the previous implementation? Use the imperative, present tense (”change“, not ”changed“ or ”changes“) to be consistent with generated messages from commands like git merge.

FoundationPress has a history of uninformative or non-existing commit message that makes it hard for anyone else to understand the reasoning behind changes, especially as time goes by (like the example above with removal of package script).

I come back to FoundationPress from time to time and try to read up on changes in code and it's time consuming and sometimes impossible to track down the reasons for changes. (And since it happened more than once that untested, unwanted changes or even misstakes has been committed from pull requests I want to know why changes are made, it's easier to catch errors then.)

[joshtipton28]

I agree with Aetles. It is very time consuming to try to catch up with the changes every time I pull a fresh copy. I think that in addition to good Commit Messages, that a Changelog would be very helpful. I just currently feel like I'm in the dark every time I start a new project.

One particular instance is the recent change from compiling everything to the assets directory to now compiling to the "dist/assets" directory. This was an unexpected change that would have been nice to have in a changelog with a brief explanation of why the change was made. I'm definitely cool with making things better, but I like to understand why and if I have to dig through a million things to find out why, it can get to be frustrating.

[jshwlkr]

Potentially https://readthedocs.org/