Update Website & Documentation #323
Comments
PhrozenByte
added
pri: Low
type: Enhancement
info: Website
type: Idea
and removed
type: Enhancement
labels
PhrozenByte
changed the title
PhrozenByte
added
info: Meta
pri: Normal
info: Feedback Needed
and removed
info: Website
pri: Low
labels
I lied, I have one more comment to make tonight. I'm not sure if this is what you mean or not, but I definitely think these "Read More" links need to stand out better. When I worked on the If you're skimming the page, the link is practically impossible to notice. The heading I added to the Nginx section in my PR is a partial solution for this. I wanted it to be visible to someone who was looking specifically for the Nginx documentation. It's not a complete solution obviously, as we probably don't want a new heading for every time we need to go "hey, we wrote a page about this". Anyway, just in agreement that there's an issue. I don't know yet what the solution is, but even a giant: Read More: Upgrade Pico 0.8 or 0.9 to Pico 1.0would be an improvement. (And if you actually meant "We need a better way to organize the |
|
@smcdougall: See http://picocms.org/docs/#upgrade resp. 13c5255...484afa0 Probably not the final solution... However, I don't like how we present our documentation in general - apart from its content-related shortcomings... Unfortunately I've no idea how to solve this. I don't have time to substantially extend and revise the docs... 😞 |
|
First of all, you've probably noticed, but there's a small text shift when you hover on "Learn More..." For some reason, the smaller text seems to take up half a pixel more than the big text, causing the paragraph below to rise slightly when you hover. The size of the h2 goes from 27px down to 26.5. It's an odd behavior, and the only fix I could find was to set a height on the h2 (not a good solution, just an observation). Actually, another solution could be to give it a I'm not sure if I like the current style of the "Learn More...". It's definitely an improvement over nothing, but for some reason it makes me think it's going to pop up one of those annoying JavaScript help bubbles. You know, when a poor-quality website says something confusing and has to stick a I'd like to help out more with the Documentation. I've been meaning to ask about it for... awhile now. As you've seen with the I just need some direction. "Extend and revise the docs" has always been a bit vague. If you can come up with some guidelines to what kind of changes you'd like to see, I'd be happy to work on it. Tomorrow (4/27) I should have some time to continue the Nginx page. If you want to give me another project to start on after that, just let me know. 😉 |
|
Yeah, I don't really like the solution either, but it was the best I could accomplish without changing everything 😄 The problem is that I don't have a real direction either. The docs just seem to be unsatisfying in whole. The only sections I really like are the parts taken from the There should be much more content about how to create pages, what Markdown is, the Regarding the "how to present the docs": I like https://readthedocs.org/. But we don't have the content to split it up into many subpages... Despite the fact that the current docs are actually too long and to varied for a single page. |
|
I'll start going through everything and see what I can come up with. I think I get what you mean though. What we've got now is the simplified, overview of Pico. We have the short, simple examples that are designed to
With that basis, it seems what we lack falls into two categories.
We should expand the documentation from mostly being on a single page to wiki-like levels of detail. It should provide more information than you need to know, but in a way that's optional and doesn't feel like required reading. Perhaps the reason we've gotten a few issues like what I mentioned above is because Pico's identity is still a little under-represented in the current documentation. The website briefly describes what Pico is, but now how it should be used. Pico isn't a turn-key solution, but rather a slim and powerful platform that, with a little perseverance, can be much more personalized and elegant than the competition. While software like WordPress exists to be that turn-key solution, it's a bloated, heavy, and hard to customize experience. It can be great until you hit that brick-wall of discovering that you can't accomplish what you wanted with its existing themes and plugins. There are far too many static websites out there that were built on WordPress out of convenience. (I'm not trying to solo out WordPress here, it's just the example I was using.) Pico's documentation needs to help a user better understand what Pico is, and why they might want to use it. "A stupidly simple & blazing fast, flat file CMS". Great, but that's the what, not the why. "Pico is a lightweight, easy to use framework for building and managing a customized website using simple Markdown files." Okay, that's not great either, but I was trying to cram it into one sentence. 😆 I think I've rambled a bit here, so /rant. The last thing I wanted to touch on was my writing style. With the two pages I've done so far, I've tried to go for a "tutorial speak" tone of voice. I've been trying to use casual language to explain things with a little more personality. The current Pico Documentation is a little more sterile, but I feel like overall it too was going for that more casual approach. Personally, I think it makes the reading less intimidating than, say, trying to read manual pages for example. I'd like to continue this tone with any new content and keep Pico looking like a friendly option. Perhaps try to build up a community a bit while we're at it. 😃 What do you think about this tone? I don't want it to sound too much like "hand holding", but I'd rather that than sounding too much like a robot. |
|
Actually, in relation to that rant.... Maybe that's the best place to start! A page detailing "What is Pico". It's something very noticeably missing from the existing docs. Other than the bullet points on the splash page, there's really no information on what Pico is. Right now, the Documentation jumps right into How to Install Pico, without going onto why you'd even want to. |
|
Sorry for the delay, I wanted to read the final version of the nginx docs first. You've written so much, but I'm not sure what to answer other than "Yes, you're completely right" and "Full ACK" 😄 As said, I like your nginx docs and thus also the writing style. As a non-native speaker (who mostly writes in English rather than actually speaking it 😉) my language surely tends to be a little more sterile. A little more personality definitely is a good idea. 😃 Starting with a page about "What Pico is" is a great idea! 👍 |
|
Okay. I'll work on it sometime when I'm free. You see, I've stumbled a few times trying to explain to others what Pico is. "I've been working on this thing called NotePaper. It's a theme for a software called Pico. It... um... makes websites out of Markdown files. Oh, Markdown is... you know what, nevermind. I make a thing that you can use to make a website that looks the same as mine... using this other thing that makes websites." That's pretty close to the kind of conversation I've tried to have with non-techie family members. I'm sure any user that doesn't immediately understand the terms "flat-file" and "CMS" on Pico's splash page are probably feeling about the same. I want to write the page that will convince them that they'd rather use Pico than another solution. 😄 |
|
New:
|
That could be pretty cool. I plan to keep chipping away at the website after the About page is done. Since it's within my knowledge to work with it, I can focus more on the website while you continue work on 1.1, etc. 😄 |
|
Food for thought, but would a "History of Pico" page be something you think would be interesting? Or do you think there would even be enough content for one? Two main talking points could be
Just bringing it up because it was asked about in #355. |
|
What about a page called "Upstream Projects" that lists and goes into some detail about which upstream projects Pico is built on? I don't think this information is actually listed anywhere at the moment... |
Sure, why not? 😃
They are listed in Pico's |
|
Yeah, I was thinking of a combination of "thanks" and "blame them". 😆 Since they aren't listed on the website though, many users may not realize Pico is built on existing technologies. I've seen plenty of Issues opened about upstream bugs (yesterday's being what made me think of this). I doubt it would reduce the number of these Issues, but it would at least be a place people could reference or that we could point people to. |
|
@smcdougall: See https://github.com/picocms/picocms.github.io resp. https://picocms.github.io/ I think that I've changed every reference to the |
|
Some brief searching in Atom doesn't reveal anything. I'll keep an eye out for issues though. Those When will |
Soon, I'll contact @picocms to migrate the domain. |
|
Hmm... I was wondering, should we manage Issues regarding Pico's website (including Pico's docs) here or in the picocms.github.io repo? What do you think @smcdougall? |
lol, I figure that would be part of the process. Good luck with that.
Probably over there, but I guess it depends on how you want to treat it. It could be treated as a separate entity, or we could consider it as more of a "dummy repo" that's just for code. There's also some of GitHub's integration to think about. It's much easier to link to and discuss items belonging to the same repo. I think I'd lean toward migrating things over there, but I'll support whatever you decide. You've got a little more experience dealing with these sort of things. 😉 |
No, this shouldn't be a problem anymore, I was able to contact him. 😃 He did it already, http://picocms.org/ is now served by the |
|
The |
|
@smcdougall: Since you finally are a Collaborator, do you want to take responsibility for the website and the docs? Just making things "official" which are already reality. 😆 Naturally, I'll still read most Issues and PR's, and give feedback when I think it is necessary (especially when you tag/mention me/ask for feedback), however, I would like to hand over the "daily work". |
|
Sure. 👍 I think I can handle it. 😄 |
|
Since there are no open discussions I'm moving this to picocms/picocms.github.io#7 😃 |
This is a long-live issue to track and discuss wished updates of our website resp. documentation.
Website
_development/collection resp.development.md_cookbook/collection resp.cookbook.htmlportfolio("Showcase") to re-implementcustomization.mdwith extended information about and screenshots of all plugins and themes_data/plugins.mdand_data/themes.md) to make adding plugins/themes much easierphpDoc.htmland_data/phpDoc.mdas a referenceupgrade.mdornginx.md(Improve Nginx Documentation #343))content/folder)<h2>headers with a floating box in the TOC-reserved space on the left, see About Page #349 (comment) for an exampleDocumentation
CONTRIBUTING.mdto the "Getting Help" sectioncomposer require picocms/Picoand provide a appropriateindex.phppico-composerproject instead? See Pico 4.0 and beyond #317The text was updated successfully, but these errors were encountered: