[FEAT]: Proposal for several doc enhancements

[nis65]

Description

I am working with potos now since about two or three weeks. I suggest to improve the documentation as follows:

• split the "getting started" into two steps (and explain these two at the top)
  • step 1: create unchanged potos vanilla client iso (items 1 - 8)
  • step 2: change the client by changing the parameters / files of an existing role (wallpaper) (item 9, all subitems)
• create another step
  • step 3: create your own role (from the role template)

All tutorials should be as simple as possible. The goal is to have tangible success on the client soon. As I am very unhappy with the current state of the automated molecule tests, I also would suggest to forget about them in the beginner tutorials. The test framework is causing much more headache than implementing functionality. And it is not realiable: Even tough @fadnincx fixed the testing for me (and I assume the pipelines worked in his repo), my tests still fail. It is extremely frustrating when debugging the tests themselves takes three times as much time as debugging your "real" code.

I furthermore suggest:

• document the anatomy of a "live" potos client (including the mapping of files mentioned to their source repo)
  • all starts with the config /etc/potos/specs_repo.yml`. This points to the client configuration (that contains further pointers)
  • ansible-pull
    • downloads that repo (which contains the list of all needed roles and variables for them)
    • executes the "prepare" playbook (from ansible-plays-potos) which downloads the roles and copies the variables from the specs repo to the role directories.
    • executes the "normal" playbook which finally does all to the client you want it to do.
    • special role ansible-role-potos_basics: executed first, last step is replacing the ansible-pull script itself!
  • document the development options
  • how to use different branches (e.g. develop and prod)
  • how to debug a single role without going through the full "git push" / "ansible pull" cycle for every line of code
  • how to use ansible vault (pros and cons)
  • how to use ssh keys
  • how to fix the automated tests.

I did not really look into the ISO documentation as I spent most of my time with ansible-pull. But given that the tutorial was sufficient for me to create a "no questions asked" ISO is not the worst sign :smile: . But I assume to make the ISO docu right, you first need a good running client docu as suggested above.

Please advise:

• what are the priorities from project side
• I am willing and able to write most of the documentation listed above, except for the automated testing stuff (molecule).
• I assume you prefer multiple, not too big MRs to a single large one.

Additional Information

No response

[fadnincx]

@nis65 Generally agree.

As for Molecule, if you have a better alternative to test Ansible roles, I'm more than happy to test it and possibly migrate to it.