A Table of Contents in Wiki Version of ReadMe

[mcguirepr89]

Hello, again,

I have enjoyed getting familiar with sdm but have found its documentation to be difficult to navigate.

As a personal solution to this problem that I would also like to share, I have moved the ReadMe content over to the GitHub wiki and am reformatting it as MediaWiki so that sections are properly indexed for quicker reference.

This is how it looks so far -- I will share it with you when I'm finished and you can keep it if you'd like.

My best,
Patrick

Update

It is finished -- I didn't alter anything, just formatted things for MediaWiki to take advantage of the Table of Contents.
You're welcome to make a pull request or just copy and paste it if you want it for the repo. Like I said, this was mainly for me.
Thanks again for sdm

Another Update and more unsolicited thoughts

I've thought about this a little more and want to add the following:
I would be happy to maintain a Wiki for you--through pull requests or whatever-- since I know having the same info in two places is worthless. I wanted to offer this so that you can pare down the ReadMe and make it really consumable.
I think sdm is very valuable and INCREDIBLY powerful. I think of it as the caddy of image altering. Being such a powerful tool, I think the ReadMe should highlight those things succinctly and really showcase what sdm can do for all kinds of use-cases.

I truly will not get my feelings hurt if these are things that do not interest you, but please let me know.

My best!

[gitbls]

While I see the value of the table of contents, I personally find it a bit shocking when I go to your link and see nothing but the TOC. It's great, but stark and striking. I also don't understand what the column on the right side is.

Is there any way to get just the TOC down the left side of the existing README (that is, the text and the TOC are displayed side-by-side)?

I agree with you sdm is extremely powerful, and I have a couple of other things that I could add to a set of examples. I've always assumed that I'd add them to the Discussions section (under a new Tips and Tricks category, but have been a bit busy and haven't started on this yet.

Have you watched the video I made? Tips and Tricks videos are another idea, but holy smokes! Making a video is quite time-consuming!

Thx

[mcguirepr89]

I personally find it a bit shocking when I go to your link and see nothing but the TOC. It's great, but stark and striking.

I agree that the layout is striking and does not make things better. Approaching sdm headon looks like that Table-of-Contents -- it is intimidating and hard to navigate. I believe that can be mitigated greatly by breaking the information into smaller logical structures. With headings (and nested heading indicating relationships between and among other topics) that reflect a more common API documentation, you stand a much better chance at having sdm consumed more readily.

I also don't understand what the column on the right side is.

This is built-in GitHub Wiki navigation. It expects that you place documentation in the Wiki so that GitHub can automatically index it for you. The TOC for MediaWiki appears redundant when ALL information is one continuous document, as in the README and the unchanged version I converted to MediaWiki formatting.

Have you watched the video I made? Tips and Tricks videos are another idea, but holy smokes! Making a video is quite time-consuming!

Even after combing through the README for reformatting, I didn't even even notice the video link. This is another reason why the README desperately needs rethinking.

Please consider doing something more standard, like: Intro, Install, Usage, Advanced Usage, Troubleshooting, Notes.
If you refer everyone to your Wiki for advanced usage and "Tips and Tricks," then you won't have to bombard ALL users, including those who may simply be curious at the outset, with the potential contained within each and every flag. I suspect many users who would have used sdm bowed out after several hundred lines of information they could not yet digest for fear of getting themselves invested into a behemoth they could not properly control.

[gitbls]

Thanks for your thoughts on this. I agree that it's past time for a documentation rethink.

I'll take a look at it and put a plan together.

[gitbls]

First pass done on moving things into the Wiki. Still need to review all links, etc, but would appreciate your thoughts on this.

[mcguirepr89]

I think this is a tremendous improvement in documentation and lowers the barrier to entry in using sdm -- great work and I do think you're going in the right direction. The video link now feels properly featured and the first exposure in ReadMe does a great job in communicating the potential and the power bound in sdm without over-doing it for new users. Distinct pages organized by the Wiki are MUCH easier to navigate and having each topic receive its own page hints to the user that each feature is a powerful and potentially useful as the last.

I say you've righted the ship and should now feel even better about letting the wind in your sails push you forward without worrying that you're leaving anyone behind!

My best,
Patrick