Sceptre: Improve Readability in Docs

[cbivans]

The doc has been lacking in examples, and some clarifying words like how template_path is supposed to be used in 2.x (e.g. No templates directory name first).
The effect of the issue is that some people may be unsure on how things are done and the expected format of options and config.
Many errors because of slightest syntax issue that may or may not be obvious. This issue is not to add validation for input (which would be nice) but to make the documentation more readable so input would be cleaner.
Existing examples would be double-checked for syntax issues.
Examples would be added to sections that have none or add more as needed.

Examples of things to improve:
Some sections use a link with a '#' name but that bookmark does not work (doesn't jump to right part).
Terminology section doesn't explain what a Stack or StackGroup is and the first definition refers to them. Getting Start briefly mentions them but also doesn't define.
Command line interface has very few examples of option syntax (the input it expects).
Mention templates path starts off relative from 'templates/' directory and not from Sceptre project folder like sceptre 1.x did.
Many others.

[cbivans]

I'd like to work on this. I'd also like to do the broken links issue.

[nunogrl]

I've been using sceptre 1 and I also struggled to migrate to 2.
I'm really happy with the improvements brought in, but I've spent way too much time to be able to take the benefits in due to the lack of practical examples of daily basis operations:

• change-set management;
• jinja2 examples;
• usage of built-in variables;
• etc...

Looking forward to contribute as well

[ngfgrant]

Hey folks

Appreciate bringing the above to our attention. Best course of action is if you see something that looks like a good improvement to the docs then just make the change and submit the PR. Those sorts of things will get merged quickly.

[1oglop1]

@nunogrl @cbivans We have put a lot of effort to enable the community (you) to help us with docs improvements. All contributions are more than welcome.

[et304383]

This is a symptom of sceptre 2.x being much more difficult to understand and use than sceptre 1.x.

This tool used to be amazing. Then it became a nightmare with 2.x. It's why we've told all developers to stick with 1.5, well, forever.

Until someone develops a new tool that is as easy to use as was the case with 1.x.

[craighurley]

@et304383 - "nightmare" is a bit over the top?

I (and my colleagues) have been happy users of both 1.x and 2.x. Sure, certain things could be better (like pretty much most tools), but as indicated in prior posts here, the maintainers welcome PRs to help improve anything you see as an issue. Do you have time to help improve the tool?

[et304383]

@craighurley it's an opinion thing. To me, and many of my colleagues, the complexity introduced in 2.x provided little to no value over 1.x.

I don't have time to improve the tool. Tools are supposed to save us time, not add to our work effort trying to make them better when they take steps backwards.

I appreciate everything the Sceptre team delivered in 1.x and that's why we continue to use it.

[1oglop1]

Open-source is worth as much as you can contribute back.

[ngfgrant]

Hey @et304383,

From our previous discussions I know you are not a fan of v2. Still hope to win you over with v3 though 😉.

As a bit of context, it was actually one of the v1 original authors who set forth the v2 "vision" and I've tried to meet that vision the best I could.

Mainly:

• a more consistent cli set of commands i.e. grouping create etc.
• a better way to read config
• pip installable plugins (I know that's a point of frustration for you)
• clearer, more maintainable codebase.

The maintainable codebase part can't be overlooked. There were some really hard to understand parts of v1 that meant contributing was tricky without messing something else up. I think the changes to the codebase have been a success overall (not perfect) with more contributors to the project than when I took the reins as a maintainer. On that note I have to disagree with the comment 'little to no value' added. We've made it easier to contribute and built a bigger and better community around the tool and for me that is value.

Along the way of developing v2 I noticed that there were some subtle bugs in V1 that needed fixed that that was mainly in the way dependencies were handled. Fixing this, which I still think is good and right to do, has caused some issues with directly porting v1->v2. I agree if you are going from v1 to v2 the upgrade path was not direct and expected v1 behaviours didn't directly work with v2. However, if you are relatively new to using the tool - which most of our users are - you don't have the migration to follow and can start fresh with v2, there are less issues.

Over the last couple of years I've learned a lot about this tool and the tooling that around it and hoping that will show through in future versions.

Really, I am genuinely sorry to hear you are not getting on well with v2. If you want to open up an issue with some specific suggestions for v3 then I'd definitely take them onboard. Let's keep this issue to specific documentation ideas.

Cheers,
Niall