nushell / nushell/nushell.github.io
Move Philosophy into Book
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 258
- Forks
- 561
- Avg merge
- 3h 20m
- Merged PRs (30d)
- 15
Description
The book does a great job on the How. It explains well how Nushell works. But it lacks a bit on the Why. The Introduction hints on it but it seems to get lost on the surface, e.g. "modern style of development", "modern feel", "UX polish". New users tend to want to know the Why first before the How.
The Philosophy section of the Contributor Book does a great job on the Why. But it's usually read only long after the How and only by people interested in the underlying details.
I'd like to propose moving the Why before the How. This means moving the Philosophy section into the main book before any concrete "Usage" sections. It would probably make sense to put it just after the Installation section.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Compare the Philosophy section in the Contributor Book with the main book structure, especially the Installation and Usage sections. Move Philosophy into the main book after Installation and before concrete Usage sections; done when the Why is presented before the How and the old Contributor Book placement is handled.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 45/100