lirantal/nodejs-cli-apps-best-practices

Updating layout suggestions

lirantal opened this issue · 26 comments

lirantal commented

What are your thoughts around organizing the layouts a bit differently?

Some feedback I received is around:

  • Getting rid of the collapsible content such as in Details or Recommended packages part and then just defaulting to that content being visible straight-out.
  • Adding a TL;DR for the top of the guide instead of the short intro, is that more helpful or not much of a change of what we have today?
  • Should we add more space between items and also between end/beginning of sections?
  • I want to add a contributors section too based on https://allcontributors.org/
lzm0x219 commented

The existing bug of gitlocalize can be circumvented by directly displaying the details. I think it is helpful to add TL;DR.

lirantal commented

Sounds good, I'll plan for both of these updates then 👌

lzm0x219 commented

Great!👏

lzm0x219 commented

Will you consider building a documentation website?

lirantal commented

I'm open to do that if someone wants to suggest pushing a docs directory for it and then we can also easily host it on GitHub Pages.

lzm0x219 commented

Yeah, it's great! I've been working on a vuepress theme recently. what tools are you going to use?

lirantal commented

Didn't have anything in mind so whichever works and Vuepress is fine with me. Will it handle the current markdown style we have on the README though?

lzm0x219 commented

It can be handled. Vuepress makes people focus on writing documents.

lirantal commented

Can you provide an example of a markdown type of README page and how does the vuepress visuals of it look like?

lirantal commented

If you can put up a quick example of how the README would look like that would be great. I was hoping for some kind of layout where the table of contents would be on the left, and the right would have the actual content and so navigation will be really easy.

lzm0x219 commented

I am still developing such a theme, maybe https://v2.docusaurus.io/ is more suitable

lirantal commented

That's ok. Not super important and we'll get to it later on is just fine.

lzm0x219 commented

👌

lirantal commented

@all-contributors please add @vvni for translation

allcontributors commented

@lirantal

I've put up a pull request to add @vvni! 🎉

lirantal commented

@all-contributors please add @terkelg @jasonkarns for content
@all-contributors please add @davesag for maintenance

allcontributors commented

@lirantal

I could not determine your intention.

Basic usage: @all-contributors please add @Someone for code, doc and infra

For other usages see the documentation

allcontributors commented

@lirantal

I've put up a pull request to add @terkelg! 🎉

lirantal commented

@all-contributors please add @jasonkarns for content

lirantal commented

@all-contributors please add @davesag for maintenance

allcontributors commented

@lirantal

I've put up a pull request to add @davesag! 🎉

lzm0x219 commented

🎉

  • 👍1
lirantal commented

I'll figure out the spacing later.
I think can close the issue for now