search

picocms / Pico

Pico is a stupidly simple, blazing fast, flat file CMS.
http://picocms.org/
MIT License
3.85k stars 615 forks source link

Update Website & Documentation #323

Closed PhrozenByte closed 7 years ago

PhrozenByte commented 8 years ago

This is a long-live issue to track and discuss wished updates of our website resp. documentation.

Website

Documentation

mayamcdougall commented 8 years ago

Add a sane way to add "Read more..." pages

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 Upgrade page a few months back, I had to struggle to find the link to it at first. Same thing goes for this Nginx page.

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

would be an improvement.

(And if you actually meant "We need a better way to organize the read more markdown files, then maybe add another bullet for "Making read more links more obvious".) :wink:

PhrozenByte commented 8 years ago

@smcdougall: See http://picocms.org/docs/#upgrade resp. https://github.com/picocms/Pico/compare/13c5255d376612d748430d2bc5281813d14c920d...484afa03265d4a24f7eb594d5d60448da322cef9

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... :disappointed:

mayamcdougall commented 8 years ago

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 position: absolute to simply remove it from the flow of the document.

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 (?) next to it with a pop up explanation. I don't know why, but that's what it makes me think of.

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 Upgrade and Nginx pages, I can write a half-decent document when I set my mind to it.

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. :wink:

PhrozenByte commented 8 years ago

Yeah, I don't really like the solution either, but it was the best I could accomplish without changing everything :smile:

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 README.md (Install, Upgrade, Run - they should be as short as possible to give users a clue about how easy this whole process really is - and most of Contributing and Getting Help), the upgrade.md and the things of nginx.md I've read so far (I'll read it in whole after you've finished it btw :smiley:)... Everything else (i.e. the things taken from the inline user docs) seem... just abridged (don't get me wrong, they're fine for the inline user docs and as kind of example content, but not for our real user docs).

There should be much more content about how to create pages, what Markdown is, the %…% placeholders, how pages are accessed, how to manage assets, how the meta header works, what YAML is (I don't know a single good YAML tutorial :unamused:) - and the completely missing developer docs (at least we've something about how to create themes in the regular docs... even though very superficial... but we actually have nothing about how to create plugins). To sum up: Everything. :unamused:

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.

mayamcdougall commented 8 years ago

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

  1. Get the user setup with Pico as quickly as possible and
  2. Not overwhelm the user with too many details.

With that basis, it seems what we lack falls into two categories.

  1. Expanded sections that provide broken-down baby-steps explaining the how's and why's of using Pico. Information on Markdown, YAML, Twig (and more specifically its role in Pico), Creating content, personalizing your experience, etc, etc. If we get more issues opened by... one user in particular, these should be docs that we can point to saying "Did you read this first? It explains everything you've just complained about."
  2. Expanded information and tips for advanced users. Deep dives into examples of Theming and plugin development. Ways to use Pico in more elaborate situations. Examples that show how Pico can be used for any level of project, not just a simple website with a few pages.

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. :laughing:

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. :smiley:

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.

mayamcdougall commented 8 years ago

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.

PhrozenByte commented 8 years ago

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" :smile: 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 :wink:) my language surely tends to be a little more sterile. A little more personality definitely is a good idea. :smiley:

Starting with a page about "What Pico is" is a great idea! :+1:

mayamcdougall commented 8 years ago

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. :smile:

PhrozenByte commented 8 years ago

New:

mayamcdougall commented 8 years ago

Use Webpaint portfolio to re-implement customization.md

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. :smile:

mayamcdougall commented 8 years ago

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.

mayamcdougall commented 8 years ago

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

PhrozenByte commented 8 years ago

Food for thought, but would a "History of Pico" page be something you think would be interesting?

Sure, why not? :smiley:

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

They are listed in Pico's composer.json :wink: Don't know whether regular users care about this. However, the projects should be mentioned in the corresponding docs sections (i.e. Parsedown in the "Text File Markup" section). Apart from that we could include their logos somewhere... Maybe a "Thanks" page or something like that, could be supplemented by a list of Pico's contributors (see e.g. http://twig.sensiolabs.org/contributors).

mayamcdougall commented 8 years ago

Yeah, I was thinking of a combination of "thanks" and "blame them". :laughing:

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.

mayamcdougall commented 8 years ago

Hmm... I think you can check off that reference to #349 (#352) now. :wink:

PhrozenByte commented 8 years ago

@smcdougall: See https://github.com/picocms/picocms.github.io resp. https://picocms.github.io/

I think that I've changed every reference to the gh-pages branch, but the four-eyes principle is probably a good idea here...

mayamcdougall commented 8 years ago

Some brief searching in Atom doesn't reveal anything. I'll keep an eye out for issues though.

Those _config.yml variables sure come in handy when migrating. :wink:

When will picocms.org point to the new repo?

PhrozenByte commented 8 years ago

When will picocms.org point to the new repo?

Soon, I'll contact @picocms to migrate the domain.

PhrozenByte commented 8 years ago

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?

mayamcdougall commented 8 years ago

Soon, I'll contact @picocms to migrate the domain.

lol, I figure that would be part of the process. Good luck with that.

should we manage Issues regarding Pico's website (including Pico's docs) here or in the picocms.github.io repo

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. :wink:

PhrozenByte commented 8 years ago

lol, I figure that would be part of the process. Good luck with that.

No, this shouldn't be a problem anymore, I was able to contact him. :smiley: He did it already, http://picocms.org/ is now served by the picocms.github.io repo.

PhrozenByte commented 8 years ago

The gh-pages branch is now officially abandoned in favor of the picocms/picocms.github.io repo, see 5956c50. Please have an eye on broken links, images, references to the gh-pages branch or similar.

PhrozenByte commented 8 years ago

@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. :laughing: 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".

mayamcdougall commented 8 years ago

Sure. :+1:

I think I can handle it. :smile:

PhrozenByte commented 7 years ago

Since there are no open discussions I'm moving this to picocms/picocms.github.io#7 :smiley: