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

Question

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

Closed this issue 7 years ago · 15 comments

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 👎 / 👍 ?

Answer 1 · 2017-10-19T09:14:15.000Z

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

Answer 2 · 2017-10-19T09:32:20.000Z

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.

Answer 3 · 2017-10-19T09:36:03.000Z

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.

Answer 4 · 2017-10-19T09:38:39.000Z

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).

Answer 5 · 2017-10-19T09:41:20.000Z

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 😞

Answer 6 · 2017-10-19T14:15:05.000Z

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

Answer 7 · 2017-10-19T14:23:25.000Z

@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?

Answer 8 · 2017-10-19T14:26:33.000Z

Will the result still be one single-page?

Answer 9 · 2017-10-19T14:30:19.000Z

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

Answer 10 · 2017-10-19T14:31:44.000Z

Nope. @krnlde

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

Answer 11 · 2017-11-06T14:42:23.000Z

@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.

Answer 12 · 2017-11-06T16:37:00.000Z

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

Answer 13 · 2017-11-06T17:06:10.000Z

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

Answer 14 · 2017-11-06T17:06:48.000Z

Which may be splitted up in multiple pages

Answer 15 · 2017-11-07T14:34:19.000Z

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