Consider reworking "Demos" page into "Tutorials"

etcd-io / website

etcd.io

https://etcd.io

Other

147 stars 296 forks source link

Consider reworking "Demos" page into "Tutorials" #402

Open nate-double-u opened 3 years ago

nate-double-u commented 3 years ago

As per https://github.com/etcd-io/website/issues/267#issuecomment-841706384

Consider reworking the demos into tutorials

The Demo page has a lot of good information on it. It could be broken up into several pages, and a new Tutorials page made to house them.

rgrupesh commented 3 years ago

@nate-double-u I would like to work on this issue. Please assign me.

chalin commented 3 years ago

FYI, from https://github.com/etcd-io/website/pull/490#pullrequestreview-761287141:

... > The Demo page has a collection of little "how-to's", including one for authentication.

Maybe what we need to do is to convert the Demo page into a "How to" page (or collection of pages). Cf. #402.

Possibly as a first step (before such a conversion), you (@Somoshree) would move the text that you added here into a new section of the Demo page? I'll let @nate-double-u and @spzala comment first.

chalin commented 3 years ago

To be clear, I think that some of the entries don't qualify (have enough material) to warrant being referred to as a tutorial, though some might. On the other hand they might make sense as a quick/short "how to" (of course we can find another term if y'all prefer).

Somoshree commented 3 years ago

I too agree with @chalin . What I felt after going through the Demo page is that there isn't enough material to rework each of these sections into separate tutorial pages. Also sections like "Get by prefix", "Delete key" etc. such sections have already been referenced in "Interacting with etcd" page and doing tutorials for these would be a duplication.

jberkus commented 3 years ago

Duplication is OK. What we're talking about is having a section of solution-oriented docs, as opposed to the reference-oriented main docs. That often results in duplication of material. Not having enough content is something else, though.

I'd suggest calling it "HowTo" instead of "Tutorial", though. Per comments above, Tutorial implies a complete end-to-end example, rather than "how do I do X?" which could be just a snippet -- and better matches the content we have.

jberkus commented 3 years ago

So, looking over the Demo, here's my thinking by section:

Set Up A Cluster --> should be part of install docs
Access etcd --> should be part of "Interacting with Etcd"
Get by Prefix --> stub for "How To Get Keys by Prefix"
Delete --> stub for "How to Delete Keys"
Transactional Write --> stub for "How To Make Multiple Writes in a Transaction"
Watch --> stub for "How to Watch Keys"
Lease --> stub for "How to Create a Lease"
Distributed locks --> stub for "How To Create Locks"
Elections --> stub for "How To Do a Leader Election"
Cluster Status --> stub for "How To Check Cluster Status"
Snapshot --> stub for "How to Save The Database"
Migrate --> stub for "How to Migrate from Etcd2 to Etcd3"
Member --> stub for "How to Add and Remove Members"
Auth --> should become part of new Authentication documentation (#505)

nate-double-u commented 3 years ago

Do we want to put these stubs into a section? Or just have them in the v3.5 folder?