Question: Is there a proper documentation page?

[jolo-dev]

As much as I love Github's readmes, but doing the whole documentation within a single Readme is sort of inefficient. Especially if there is a lot.
Is there a documentation page?
If not, why not using Github Pages ;)

[romkatv]

As much as I love Github's readmes, but doing the whole documentation within a single Readme is sort of inefficient. Especially if there is a lot.

I hear you. The documentation story is pretty bad. Not only it's difficult to navigate but it also doesn't document the majority of functionality.

Is there a documentation page?

The homepage (README.md) and ~/.p10k.zsh are the only documentation pages.

If not, why not using Github Pages ;)

No particular reason.

[jolo-dev]

Have you ever thought about one?
Maybe a Sphinx could be published as a Github page, right?

[romkatv]

Have you ever thought about one?
Maybe a Sphinx could be published as a Github page, right?

Maybe.

Is this something you'd like to try?

[jolo-dev]

Yes, let me try :)
Or as an alternative, @romkatv you could enable the wiki like Oh-my-zsh did.

[romkatv]

I don't want wiki. It allows anyone to post anything and it appears authoritative.

[jolo-dev]

Okay, I see then let me try the Sphinx Documentation ;)

[romkatv]

let me try the Sphinx Documentation ;)

👍

[jolo-dev]

I had been working on a it.
https://jolo-dev.github.io/powerlevel10k/

However, the github action for CD is not working yet...

[romkatv]

Looks cool!

[jolo-dev]

Thanks!
I could do a pull request but you need to deploy it.
For some reason, the Github action with python is not working (actions/setup-python#162).
What do you think?

[romkatv]

Give me more details. What will I need to do, when, and what effect will it have.

[jolo-dev]

I have created this with MkDocs which you need to install via pip

pip install mkdocs

Then you simply needs to run

mkdocs gh-deploy

That would create a branch gh-pages and you need to put in the settings of this repository the Github Pages to that branch.

Find more here:
https://www.mkdocs.org/user-guide/deploying-your-docs/

[romkatv]

I've played around with https://jolo-dev.github.io/powerlevel10k/. It looks nice but it's not something I would enjoy using myself. I've looked around and found this alternative to mkdocs: https://github.com/slatedocs/slate. I really like that you can use built-in search from your browser, and that the navbar automatically expands when you navigate to a section with nested headings. There is also place for code samples, which would come in handy when I finally get around to writing a reference manual for all settings.

[jolo-dev]

Absolute valid point.
Let me try slate. And will come back to you

As an alternative, I found https://docsify.js.org/ quite beautiful as well.

[romkatv]

Absolute valid point.
Let me try slate. And will come back to you

Looking forward to it!

As an alternative, I found https://docsify.js.org/ quite beautiful as well.

Does it support collapsible havbar? The examples I could find don't have this feature.

Here's what I mean. Open https://slatedocs.github.io/slate and either scroll down or click on Kittens on the left. Notice that you are still on the same page (only the fragment of the URL has changed) and that Kittens in the navbar has been expanded to show subheadings.

[jolo-dev]

@romkatv I changed to slate:
https://jolo-dev.github.io/powerlevel10k/

Please, let me know what you think. If you have a logo, please let me know.

[romkatv]

This looks great! I love the logo 💯

Commands look weird in a few places but this should be fixable. What do I need to do to push it under https://romkatv.github.io/powerlevel10k/ ?

[cybardev]

Is it supposed to look like this? I think it'd be nicer to have the code in the main body instead of to the side (just my opinion tho).

---

What do I need to do to push it under https://romkatv.github.io/powerlevel10k/ ?

If there's no reply then you can clone the gh-pages branch (link) of his repo and push it to the gh-pages branch of this repo (make it first).

Then you can activate it in the repo settings like this (the source settings):

[Altair-Bueno]

Any updates on this? The last link jolo published is down.

I agree .p10k.zsh does a good job on self explaining everything but it's kinda hard to get started. p10k should have a proper wiki/reference

[romkatv]

Nope, there is no update on this. I haven't done anything.

[Altair-Bueno]

Oh i see. Can't help much with the docs, i'm unfamiliar with the config options. I just can offer some ideas.

In the meantime

From what i've read @romkatv isn't a fan of Github Wikis, but have you considered Github Discussions? It's a more open approach and will offload Github issues. The more general questions about how to do things could be posted there, while the more important stuff like bugs will be collected under Github Issues. It would also serve as documentation for p10k.

Feature requests could be also made there. A pinned discussion where everyone can upvote features, instead of being randomly published under Issues

For instance, this kind of issues could be re-posted under Discussions:

• [Question] Prompt at the bottom of the terminal window? #563
• (How to) Add right prompt element for processor architecture? #1635
• How to apply those colorful prompt themes to the SSH connected remote server? #1579

FAQs could be pinned inside Discussions, making the README smaller

Troubleshooting could be pinned inside Discussions, making the README smaller

Here is an example of Github Discussions

Yes, people could technically still open duplicate issues asking trivial questions, but we can limit that using issue templates

For the static site

mdbook is a good site generator. It's what Rust and Cargo use for their docs. A GitHub action could run each time the docs folder is updated, and modify the static website.

---

I've struggling to find a reliable, single source of truth besides the .p10k.zsh config file. This project is so huge it really needs some kind of documentation. Google is really my friend here, but a well organised documentation would be easier for all.

Personally, Discussions seems like a win-win for everyone. Everyone can ask, everyone can answer and everything is well organised. Maintainers receive less issues and users have some kind of reference

[romkatv]

What's the difference between discussions and issues. Aren't they the same?

For free-far-all discussion there is gitter. It's linked from the top of the homepage. I like it significantly less than issues but some folks prefer it. Gitter communication -- just like issues -- is of the kind where others ask and I answer, so it's not much of a community. r/zsh subreddit is another venue for asking p10k questions and it has similar dynamics.

Just to clarify, the bottleneck is my time and willingness to work on this. Powerlevel10k is one of my hobby projects (the most popular but not the most exciting) and my priorities aren't necessarily identical to that of its users. I do believe that high quality documentation would be of greater benefit to p10k users than many other things that I spend my time on. By itself this isn't sufficient to induce me to work on high quality documentation. To be completely frank, I think the fraction of p10k users who would benefit from improved documentation is small. Most never read a word from the docs and never open ~/.p10k.zsh. Users who do read documentation are more important though, so I consider documentation overall important.

[Altair-Bueno]

Oh i didn't know p10k had Gitter. I must have passed by. To be fair it's not the most obvious link on the README 😅

About Discussions vs Issues differences are:

• Discussions don't get closed, they just are kept open for anyone interested and sorted by time
• Upvotes (best responses go up, kinda like reddit/stackoverflow)
• Categories (for example: Performance, Plugins, Segments, Theeming, Examples/Showcase, Development, Features,...)
• They both support tags (Bug, Important, zsh, Pure, single-line, double-line,...)
• Maintainers can just ignore them (if they wish to do so). It's on a separate tab so maintainers can focus on more important issues. Issues can get more simple, while Discussions get more complex and open

Considering your limited time, it looks like a good alternative to the static site docs. I believe p10k has the potential to build a small community, if given the tools. As you said, people asking and having one single person respond doesn't feel right. It will definitely take some time before reaching a mature state, but i think its worth it.

Btw, i've noticed you don't have Github Issues templates on rn. Have you ever considered turning those on? Providing a checklist for TODO items could potentially avoid duplicates and low-effort issues.

PS: I'm looking throughout Gitter and it looks more like a casual chat without any kind of categories. I'm sure the same questions get asked over and over. Doesn't it have some kind of archive system? I've never used Gitter before sorry

[romkatv]

We have quite different views on what's useful and worthwhile in projects. Many things you've listed as good-to-have are a turn-off for me in other projects. I realize that different people have different preferences and I don't mean to imply that my preferences are better than yours. Nevertheless, my views as to what would be good for my projects are primarily informed by what I like about other projects. I abhor issue templates and checklists, so powerlevel10k doesn't have them. I didn't know that discussions have upvotes -- that's a showstopper. (If I could disable emojis on comments, I'd do that in a heartbeat). Seems like discussions are essentially issues with upvotes that cannot be closed. Both of these are downsides in my opinion. Given the existence of issues and gitter, I don't think discussions will be a positive addition. Once again, I'm not saying my way is best. I just hope that you see that our values differ.

It's worth repeating that I believe in the value of high quality documentation -- the original topic of this issue. Documentation would be really nice to have. Right now there is no documentation for 99% of p10k features. Presentation is also important but it's secondary to the content of documentation.

By the way, it's extremely rare that giving me advice on how to run my projects causes any effect on me. It virtually never happens. I really value feedback of a different kind -- the one where users tell me what they are trying to achieve. If you give me advice, I'll reply politely to the extend I'm able but at the end of the day we'll go on our own ways.

[Altair-Bueno]

Sure np! What works best is what you like the most. I just wanted to come by and brainstorm a little. This issue caught my attention while looking for the docs. I've using the (almost) default p9-10k theme for quite sometime, and wanted some fresh air. When I opened the p10 file for the first time in years i was overwhelmed. There is so may options listed (plus the old p9k and hidden ones)... im the kind of guy that reads the whole documentation before typing anything haha

Thanks for the info and your work on p10k. Im sorry I can't do much more than sharing insights 😅😅.

[romkatv]

Im sorry I can't do much more than sharing insights

As I mentioned earlier, telling me what to do has no effect on what I do. Note how I'm phrasing it. I'm giving you information about myself, which you otherwise wouldn't have access to. I'm leaving it up to you to decide what you should do with this information.

The word "insight" is a property of a certain kind of information. I would definitely value it if it was given. What you are doing is giving advice. You could say that this advice comes from having an insight that I don't posses. In this case the way to impact my actions would be to communicate information that would allow me to have the insight.

I've using the (almost) default p9-10k theme for quite sometime, and wanted some fresh air. When I opened the p10 file for the first time in years i was overwhelmed. There is so may options listed (plus the old p9k and hidden ones)... im the kind of guy that reads the whole documentation before typing anything haha

This is the kind of feedback that provides value to me. You are describing your experience and issues you encounter while using powerlevel10k. Can you provide more info?

I've using the (almost) default p9-10k theme for quite sometime

What do you mean by "the (almost) default p9-10k theme"? Did use the configuration wizard to generate a config? If not, where did you get your config?

When I opened the p10 file for the first time in years

What do you mean by "p10k file"? Why did you open it?

im the kind of guy that reads the whole documentation before typing anything haha

Do you mean that you've read the whole documentation years earlier and it was not overwhelming but now it is? What documentation did you read? What did you decide to type this time that required that you (re-)read the documentation? Which documentation you've tried to read now?

[Altair-Bueno]

This is the kind of feedback that provides value to me. You are describing your experience and issues you encounter while using powerlevel10k. Can you provide more info?

Sure! Here you have some examples of things i found confusing at first. I only played with some of the basic widgets:

• POWERLEVEL9K_DIR_MIN_COMMAND_COLUMNS vs POWERLEVEL9K_DIR_MIN_COMMAND_COLUMNS_PCT vs POWERLEVEL9K_DIR_MAX_LENGTH. They all 3 basically short the dir path on it's segment, but i find difficult to completely understand their differences
• The order of elements confused me at first. For example, on the git section: Why is the POWERLEVEL9K_VCS_PREFIX under my_git_formatter? If it's a prefix, it should be the first variable you see when editing the git segment. It's confusing to have them sorted that way, although to be fair all segments appear to use this schema. Not really intuitive at first
• Can i just slap a right segment on the left side or viceversa? Is there any kind of limitation? There is nothing for or against doing that, yet almost all prompts i see keep the left segment with the basic configuration. Should the user be cautious when using segments on a different side?

I'm sure they are silly questions from a noob but they did really confuse me at first. Googling the variables didn't yield good results either.

What do you mean by "the (almost) default p9-10k theme"? Did use the configuration wizard to generate a config? If not, where did you get your config?

Yes! i used the configuration wizard. It's really good. I just disabled most right segments

What do you mean by "p10k file"? Why did you open it?

I originally had p9k installed. When i discovered p10k i switched over and removed all my old configuration, run the wizard and stick with the almost default configuration until now. I recently started tuning my .p10k file because i got bored of it's design (not because it is bad, i just needed some fresh air)

Do you mean that you've read the whole documentation years earlier and it was not overwhelming but now it is?

I don't recall much about my old p9k config. I think it originally didn't have a wizard, so you manually had to add variables and make your own prompt by hand. Not sure how i did it

What did you decide to type this time that required that you (re-)read the documentation?

p10k has a lot of stuff going on that i don't understand and i don't remember. I thought the Documentation could help me archive a better configuration and use more of it's features

Which documentation you've tried to read now?

• The p10k file
• p10 README
• p9k old wiki
• Reddit
• Search results from Google

[adrian-skybaker]

For what it's worth, I found both the installation documentation and subsequent configuration wizard outstanding.

[joshuaquek]

Oh hey just a question to add on - is there a "samples" or "examples" gallery that we can follow, like https://github.com/Powerlevel9k/powerlevel9k/wiki/Show-Off-Your-Config , but for Powerlevel10k ?

[romkatv]

Oh hey just a question to add on - is there a "samples" or "examples" gallery that we can follow, like https://github.com/Powerlevel9k/powerlevel9k/wiki/Show-Off-Your-Config , but for Powerlevel10k ?

There isn't.