chore: Move the docs from the README to do separate markdown files within a /docs directory

[mischah]

I’d like to propose moving the docs from the huge README file to separate pages within the GitHub Wiki of this Repo as mentioned in #195

Can I please get a 👎 / 👍 ?

[Paquan]

The bad consequence would be that we couldn't search for keywords through the whole docs.

[lfuelling]

I think reading/working through a README is much more easy than doing the same with a wiki.

At least that was the case on every GitHub project with the main docs in a wiki that I used until today.

[nicolaisueper]

What could be an alternative?

I agree with @mischah that our README is way too large and the Wiki seems a good solution. We just have to structure the docs so you can navigate through easy.

[mischah]

The bad consequence would be that we couldn't search for keywords through the whole docs.
Valid point. At least for now.

On the long run I would love to add the docs to the Baumeister website (as static sited generated from markdown) where the would be searchable (via algolia DocSearch for example).

[mischah]

I think reading/working through a README is much more easy than doing the same with a wiki.

At least that was the case on every GitHub project with the main docs in a wiki that I used until today.

I kinda feel that.

What could be an alternative?

We could move the READMEs content to separate markdown files in a docs folder in the root of the project.

This way we would have a navigable docs via the GitHub web interface. Like the Gulp docs for example.

Still not searchable for now though 😞

[krnlde]

Personally I hate Wikis for documentations. They are basically a dead-end (to me). Plus I like to have the documentation side-by-side with the code when I download it, not having to go to an extra link to see whats going on.

Static site search can be achieved via lunr.js

[mischah]

@micromata/ux @lfuelling @Anbe93

økay, I feel you. No Wiki then 😘

---

Could all of you Update your 👍 / 👎 for extracting the READMEs content do different markdown files within a /docs directory?

[krnlde]

Will the result still be one single-page?

[nicolaisueper]

We could implement a 'Single-Page-Docs' page on the baumeister website, I guess

[mischah]

Nope. @krnlde

This way we would have a navigable docs via the GitHub web interface. Like the Gulp docs for example.

[mischah]

@nicolaisueper Created a pull request to move the split the docs from the readme to different files.

I want to make sure that any everyone is happy with that before merging. So please leave a 👍 / 👎 either at this comment or at #210

Thanks for your feedback.

[krnlde]

I see https://github.com/Knockout-Contrib/Knockout-Validation/wiki as a negative example. It's a hell to find stuff, when you don't exactly know what you are looking for. Example: find the word required

[nicolaisueper]

So let's keep the gh readme in one file and put a searchable docs page located at the Baumeister webpage then?

[nicolaisueper]

Which may be splitted up in multiple pages

[mischah]

Jup. Closing this for now. Thanks for everyones feedback 🥇