Documentation Rewrite #6
Conversation
New "Installing" Guide, as part of the Docs Rewrite Project.
|
First of all: Please rewrite the docs on basis of Pico 2.0. As you can see in the PR there's not much work left. There are just the API updates and the (very simple) blogging plugins missing - besides updating the docs. In contrast to my previous plans I will not defer Pico 2.0 for We have something in common that is a bit... yeah, challenging for a CMS whose catchphrase is "stupidly simple". We're both very circumlocutory. The problem is: No matter what we're writing, when the page contains that much text, nobody believes us that it is going to be simple.
That made me thinking... Thus we should talk about the structure of the docs. I think it might be a good idea to have a small series of very brief pages that describe the essence of Pico. For example, the install page should consist of not more than the following:
That's it, no more text on this page! The next step is to open the browser and navigate to the website. Maybe it's even a good idea to point the user to the (then completely rewritten) sample contents, containing said "essence" of the most important topics (Markdown, YAML, configuration, themes, plugins - heavily stripped down in comparison to what we have at the moment). All advanced topics (blogging, URL rewriting, VHost config, creating themes, ...) should be on separate pages on Pico's website. Just as a side note: Please don't mix user and dev docs. The only exception are the basics about creating themes. Otherwise nobody believes us that Pico is "stupidly simple"... We really can't create docs pages that are 20 printed pages long. The problem is: I tend to write 20 printed pages, too. So this is probably going to be a pretty hard one. 😒 |
I had more-or-less planned to, but I wasn't sure how much longer it would be before 2.0. When I edit these pages, I'll have you go through with me and point out anything that needs to be revised for 2.0. The only obvious thing I know of right now is that 2.0 is mentioned in the blogging section.
On this note, I was thinking that having a single, "quick-start" page to accompany the long-form version would be a good thing. Something akin to the current Docs, but cleaned up, and with everything unnecessary removed. So, the basic experience for a new user would be (to go with your narrative):
Something like that...
Wouldn't dream of it. As I've stated in the past, my goal is to make the Documentation easier and more approachable. Is there somewhere you think I've crossed these subjects? Let me know how you want to move forward with this project. I'm more or less in the same mindset about it as my original picocms/Pico#359 description above. What do you think of the compromise idea? I think a minimalist, quick-start version should satisfy the "I know what I'm doing" types. 😉 |
As always, I didn't read the pages in whole (not until you tell me to do so), so this was mostly a general note 😆 Just take a look at the PR message for the most important changes, most notably
Yeah, this is basically the idea. IMHO it might even be a good idea to move everything except for the install section of this "quick-start" page to the sample contents, this intensifies the impression that Pico is really "stupidly simple".
There are developer instructions in the install section 😉 (Yes, I know that this is currently the case, too)
This idea doesn't address the "I know what I'm doing" types at all! It's about impression. Just adding a "quick-start" page and otherwise having 20 printed pages long docs still sends the "it's complicated" message. It isn't done with a "quick-start" page, users make the decision to use Pico not until the setup, configuration and "content generation" process is finished. Thus most users will still come in contact with the "full" docs - and if the "full" docs are 20 printed pages long, they will not unlikely abandon the obviously overly complicated Pico. We need a docs structure that doesn't send this message at all. I think the only way to achieve this is by splitting the docs into small, isolated pages. However, I'm not 100% sure about how to navigate through these pages. Any ideas? |
|
I get where you're coming from, and I'm trying to figure out where I land on the subject. There are two problems that I have with the current Documentation. The first is that in their current state, the Docs feel cobbled together. And... they are! That's how they were written. Pieces were added and removed as needed to keep them up-to-date over time, but they don't read cohesively. I had lost sight of this after growing accustomed to Pico. I knew right where to find something in the Docs when I needed to look it up. But then we started this discussion (many months ago) about how you disliked their current iteration. So I stepped back a moment and reread them. The whole, long page. And it was awful. I mean, it gets the job done, and is a pretty good stop-gap, but it feels like a rough-draft that was never finished. Next, and this kind of goes hand-in-hand, the current Docs aren't approachable. If I were trying to introduce someone new to Pico (let alone trying to describe it to a less-technical user), it would be really hard for me to say "Just read the Documentation, we've got it all laid out for you". Once you've played around with Pico a bit (or maybe if you're coming from another, similar CMS), you start to figure out how the pieces fit together and what the Documentation is trying to talk about. Once you know the context of Pico, you can understand what the Docs are trying to say. It shouldn't be like that. But. You're right. Long-winded explanation is really hard to parse from a distance (probably something like this comment 😅). As much as I like this "Guide Style" approach (spoiler, a lot), maybe it's not the right direction. Maybe if the pages I've written were instead called "The Newbie Guide", they'd feel more at home. I also feel like if I took out all the instances of "Simple/simply" and "Easy", I'd lose a few paragraphs of "content". 😖 Perhaps, for example, instead of explaining why Markdown is great, I should simply say "Markdown is great." (period) and move on. I'm not really sure. I could try to really trim down what I have now. See if I can get it to be "simple". The problem might be that I'm trying to include every last thing from the current Docs that I can. I don't want any detail left out... I mean, that is the point of Documentation, right? 😒 And for some reason I'm trying to imagine what a stylized, minimalist quick-start page could look like. If it's about making impressions, then what if the instructions were just a big blank page with icons like: 📁 ➡️ 🖥️ Honestly, it makes me think of how you install software on a Mac. 😖 And it wouldn't have to be icons/graphics either. It could just be really simple bullet points or something. The point would be more on the minimalism and empty space.
They're smaller than they were! |
|
First of all: Sorry for the late response, it was a hard week. 😒
I totally agree with every single statement you've said about the current docs! Just to make this clear, my goal is definitely not to end up with something that is like the current docs. 😉 I've (probably three) layers in mind, which build upon another and refine each other. The first layer's goal is to just install Pico and tell users how to create basic content (Like The second layer's goal is to refine the first layer. It should be highly structured in small, isolated topics, each on a separate page and a reading time below 5 minutes. It should explain users how Markdown works, what the YAML frontmatter is and about content variables. Another page explains how blogging works, yet another page how Pico can be configured. Customizing existing themes is another topic, as well as creating own ones. There should also be a page about URL rewriting and basic webserver config. It's crucial that the second layer is, in contrast to the first layer, approachable, so that you can point users to a particular sub-page. The third layer basically goes a few steps further. It describes a (still isolated!) topic in every single aspect and in every detail, basically like your Nginx Guide, the Submission Guidelines or the Upgrade page. There's no reading time limit, the page should just stay on topic and shouldn't ramble on. However, the third layer should still be approachable.
I really like this idea! However, 📁 ➡️ 🖥️ matches the (rather discouraged) use of release packages, the recommended 😄 😉 |
Hey, I thought we weren't mixing developer docs with user docs. 😜 Off topic: On that note, I also have this really weird aversion to any form of non-distro package manager. The kind that just about every language seems to ship with theses days (python's "pip", ruby's "gems", go's "get", composer, etc). Maybe it's OCD, but I hate having to mess with any sort of system files (besides configs) that should be managed by my package manager. When I read a website and I get to install instructions that are like "just run I just really really hate the idea of untracked files lying about my filesystem. 😖 Okay, so now the bulk of your comment. Overall, I think your idea sounds pretty good. I like the idea of documentation that's simple up-front, but has a lot of content you can choose to dive into. It sounds like it answers both of our concerns about the Docs. I wish I had more to say, but your description is very detailed and compelling. I think it's a great idea, and I don't have much to add to it. I'll take a look at what I've got sometime, and see about chopping it up into smaller "second layer" pages. With a lot I've done so far, I feel like every time I get to a new "vocabulary word", I have to explain it. "You're going to love using Markdown... oh, wait, I have to pretend you don't know what that is yet..." It'll be nice to not have that obligation. "Write your pages using Markdown." (Don't know what that is? Tough. Read the link, that's all you get.) 😆
No... I guess I don't know what you mean. Or, I can't think of any examples anyway. What's coming to mind though are those little symbols in the margins of "For Dummies" books though. 😆 What I'm imagining you probably mean is like a banner with a pair of glasses or something that goes:
That would go before a big block of content. Anyway. I like your ideas. I'll try to see what I can do when I get around to it. I try not to forget that Pico is a thing. 😒 😅 |
Starting with Pico 2.0 (due to Shell access is pretty common for shared hosting packages starting around 10 €. However, we still fully support release packages for users without shell access, or for people who simply don't want to use
I was thinking about creating a Debian package... But I'm not sure whether Debian's release cycle matches ours 😆 I mostly agree, but I don't think this is critical for highly user-specific things like a CMS or website contents in general.
Great! 👍 😃
That's exactly what I mean! However, we don't have to explicitly write it somewhere (because there are many people out there which basically hate this metric), it's rather a reference point for ourselves. See http://marketingland.com/estimated-reading-times-increase-engagement-79830 (just a random pick from Google 😄)
I'm looking forward to it 👍 😃 |
Yeah, I don't mind things like websites / webapps sitting in a folder by themselves on my filesystem. It's more the idea that I put them there. I know right where they are and don't have to hunt them down later. I also avoid running a
I don't know that a package would be necessary, but I definitively don't think that the Debian release cycle would play well with that. I'm just reminded of the issues they had with ownCloud. We'd either have people using ancient versions of Pico, or have to provide our own repo. And then, when a new major Pico version is released... we'd break everyone's websites the moment they try to update their packages. 😆 As an aside though, it could be neat to have some additional infrastructure around Pico. I think I've mentioned before the idea of having a place to build a community. Something like a Mattermost, Riot/Matrix, Rocket.chat, <insert popular open source messaging platform>, to act as an upgrade or extension of the IRC room. A place that isn't for development (GitHub), but is more permanent than IRC. Maybe I just want an excuse to play around with those applications though. 🤔 If that's anything you'd want to see, we could start a discussion in a new issue sometime.
Oh, reading times! 😒 I don't know how I didn't understand that before. I was thinking you meant some kind of indicator that tells the reader: "Okay, now we're serious. It's reading time." 😓 Yeah, I know what you mean by those. 😅 |
I'm not sure whether this is going to be used anyway... Currently there's (much to my regret) not much of a community. Users can simply open Issues for questions, there's no big necessity for something separate. However, if you want something more permanent, we could simply add a Bot to our IRC channel saving all (public) conversations (i.e. public logging).
🤣 |
|
Still unsure of how to proceed with the idea of more simplified docs. I made a few mock-ups of the most minimal design I could. Let me know if you like this direction or if you have any other ideas. Ignore the fact that the second block of text is the wrong instructions. I apparently didn't read it first. 😒
|
|
That's exactly what I mean, absolutely great! ❤️ 😃 There's really no need for more text about this simple step. Simply add a big "Next" button to the bottom of the page to get to the next "first layer topic". I think it might be a good idea to proceed with simple content creation, like
(Sure, we indeed need some more text here to explain the basic principles of Markdown 😄 ) btw: I like the first mockup more than the second one. However, we should probably increase the font size. I'm afraid that the Webpaint theme isn't really state-of-the-art anymore. 😄 |
PhrozenByte
force-pushed
the
master
branch
2 times, most recently
from
a0eb274 to
8cc15b3
Compare
PhrozenByte
force-pushed
the
master
branch
2 times, most recently
from
76ff0df to
138b2bd
Compare
PhrozenByte
force-pushed
the
master
branch
2 times, most recently
from
9616d20 to
0ea0cf6
Compare
|
makes TARDIS sounds 🚨 Oh, hey, look! Ancient history! I've been avoiding coming back to this for one reason that it seems might not even be valid. I forgot that apparently I was writing documentation alongside the original Docs. This whole time I've been assuming this branch would be a giant conflict with the current docs (it's been years after all 😅). I figured if I ever tried to sort it out, it'd be a giant headache of figuring out what line/paragraph conflicted with what. But no. It turns out, I wrote entirely new files for this. 😱 So... there might actually be something useful left here? @PhrozenByte, if you have some extra time (and I do mean like extra, extra time, since there's so much else I'm focusing on right now anyway), can you look through these staged files and see if you think they're worth salvaging? I'm sure not that much has changed, so maybe some use could finally come of them. (Edit: I've got them up on my GitHub Pages right now for better readability. No promises that it stays up, since that's a very old branch, but I might copy the content out of it when I switch the branch back, just as a reminder to look it over. 🤔) We can have another discussion sometime on whether you still like this "guide" direction of docs, etc. I'm mostly just wondering if the content I wrote eons ago is worth continuing. If so... I could probably get around to finishing it. Better late than never, right? ...right? 😅 🦗 crickets chirp 🦗 |
Yes! ❤️
Sure! 👍 It's Git after all. We can simply compare this branch with the latest
sounds a bit overwhelming, most of this is from phpDoc, i.e. can be ignored. Most of the contents have changed. 😒 Not substantially (it's Pico after all), but there were improvements and additions, mostly for new releases (its from Pico 1.0, e.g. still mentions By the way: I still like the idea of making the basics (i.e. install + config + Markdown/YAML + installing R2G plugins/themes) "stupidly simple" as in #6 (comment) 👍 |
I'll stick with looking at Again, I thought it'd be a headache with the changes over time, but everything I did was rewritten from scratch, so as long as I pull the changes out and recommit them, instead of trying to merge, it'd be a trivial amount of work to get going on this again.
Actually, I kind of like some of what I had written before. It's a really casual writing style that helps ease a user into Pico, especially versus the very information-heavy docs we have now. I think as long as I went through it and updated all of the Pico 1.0 stuff (which shouldn't be too much), it could be a good base going forward. These "rewrite" files lived at as a separate "Guide" item on the navigation. I feel like having a new user guide like that could still work. I also kind of like the idea of having the Docs be kind of an "As deep as you want to go" approach. Think of the current in-depth guides. If we broke out more of the technically-heavy bits into their own pages, it might be more digestible. I also do like the "Read-the-Docs" style, and I know you've mentioned it before. I think bite-size portions of documentation is the way to go. When I try to look something up now, my eyes roll back in my head and I just "ctrl-f" until I find the thing I was looking up. I must be hungry, because there's a lot of food analogies in here... 🤔 Btw, did you know you should never use pages over pages()? 😳 I guess I need to fix some things. 😅 Seriously though, that really was something I only picked up on somewhat recently. I'm still doing it!* And it makes me wonder what other changes you've buried in the old docs! 😂 (* not really, going forward I'm not, but even the most recent theme I published uses |
|
Random thing I stumbled upon... But what if the docs and or guide used branching instructions in certain places like this? GitHub Pages Docs. So, instead of cramming all the instructions inline, have a tabbed button to select between things like: How do you want to install Pico? or My web server runs: Just some food for thought. 🤔 |
|
It's 1am. I might be going a little crazy right now. But I got this coded and working! 😁
Jekyll, CSS, JS. There's a Jekyll I can't believe I got this working tonight! 😱 ...I'm going to bed now. I don't expect any replies or anything. I just really had to share this before crashing. 👋🏻😴 |
Great idea 👍 Visually: ❤️ Content-wise I'd rather move the Git- and Git-Dev-variants to somewhere else. Furthermore this definitely needs some explanation, people won't know the diff between Composer, pre-bundled releases and Nextcloud. |
Yeah, I'm pretty pleased with it. 😁 Just got to do some responsive styles, because the buttons don't currently have any way to collapse for smaller screens. I'm not too worried though, because when I did the Themes gallery recently, I found the responsive stuff wasn't that hard after all.
Maybe. I'll keep it in mind, but I did try to go into a little detail in their sections. Just apparently not the pre-bundled section. 😂 They each have a one-line intro about them, but it should probably be more like a paragraph on why you'd choose each option. Anyway. I've just been doing the work locally, so I don't have anything committed to share yet. Mostly been avoiding that because I don't know where to put these new files. The original idea was that they were a Guide, with their own navigation item in the toolbar. But at this point I think they'd be better suited as Docs (just a new, paginated version). For another sneak peek, here's the Composer section, which I think is pretty good. It's simple, but informative. It gives our recommendation to use Composer and the reasoning why. It includes a link to Composer so they could do more research if they wanted. And it includes the shell commands and their explanation.
(Also, lmao at my previous image: My files are littered with comments, but most of them are actually commented unlike that thing about the download button. 😂) (For the record, it has one now. 😉) |
|
Also, everything's a work-in-progress. I'll let you tear into it all long before it ever goes live. 😉 😂 Random thing while I'm thinking of it. I try to use simple language in it wherever I can. This leads to two problems. First, there's a bit of an overuse of words like "simply" and "just", which could probably be cut back on. But second, I've been trying to make a conscious effort to not use slang or phrases which might not be clear to non-english-native speakers. The downside of trying to write in a simple and casual manner means these tend to sneak in here and there. Although they do carry a casual vibe with them, I don't want to to accidentally alienate anyone. Installing Pico might be "easy as pie", or "a piece of cake", but I don't want to leave anyone wondering when baking entered the equation. 😅 So anyway, that's just something I want to keep in mind through the editing process. 😜 |
|
@PhrozenByte No rush here, just some Docs questions that came up while writing another comment. There is a section in the current Docs that recommends using the Should this still be recommended? I've added some text to this section about using the It seems like using Markdown would probably be the preferred solution here, and much easier for the end user as well ( If you agree, I'll change it in the rewrite so that the Also, should this example use Or it could at least use Thoughts on these? |
Definitely. The
Might be, yes. Depends on the theme and how it is being used. The default theme uses |
Huh, I guess that's all it does. It has I don't actually look at the Default Theme rendered very much considering how often I look at its code. Tagline it is then. I had more or less convinced myself by the end of that comment anyway. The fact that it is run through the Also, That's in the Docs. Right now. 🤦🏻♀️ I have my work cut out for me. *takes bow* It's okay, I laughed when I rewrote that part. Documentation is hard. I'm sure you just copied and pasted that from somewhere else and forgot to change it. I do stuff like that all the time. 😂 Seriously, I didn't include "Set your theme to Anyway, I didn't see the point in fixing this example just yet on the live version, but I can if it bugs you. Just let me know, lol. |
|
Updated GitHub Pages with my current WIP. https://mayamcdougall.github.io/picocms.github.io/docs/ Most content through "Deconstructing the Defaults" is done. Not final, but rough-draft state at least. "Creating Content" especially needs another pass at editing (I swear I worked on this one a bit, but there's still a lot of "old rewrite" content here, so idk anymore 🤔). Not necessarily looking for feedback yet unless you want to give some. I just wanted to get the current state uploaded while I continue to work on it. So this is more of an "in case you're curious" update. 😉 Tada, it exists. 🎉 I've removed most of the inline comments I had, but there's still a few in the page code. Those are just for me, you don't need to track them down. I just didn't bother removing them on commits that are destined to be either squashed or deleted in the end. I've got a long running note containing all the comments I did remove though, so @PhrozenByte, let me know if you ever think you'll have some extra time for Q & A. 😂 (If not, I'll just try to trickle some questions in here and there. 😉) |
|
I think I have a decent solution for a common Docs problem we have. 🤔
Thoughts? (Just kidding of course, but I thought of this the other day and had to share. 😂) As far as an actual update goes, I haven't done much more work lately. I went to write the Plugins page awhile back (now separate from the Themes page), and realized there just wasn't a lot of content to work off of in the current Docs. Also, @pconrad-fb tore into my "Creating Content" page (in a good way! 😉) and shed some light on some of the basics I really needed to include. Anyway. Hope you enjoyed the meme. I'm going to stop pretending I have an actual update now. 😂 |
|
Oh! Hey! Man, I've been busy. Nice to see you, and I appreciate what you're saying with that meme :D I have to think on whether Pico is blogging software, since ahem It's powering the blog part of a site that's otherwise Hugo! heh. How are you? |
|
Hey. 👋🏻 The meme is a little bit of an inside joke, lol. It’s a line from the Docs, that I feel like I’ve had to quote far too often in support threads. Pico can make a great blog as long as you know what to expect of it. 😉 A lot of times though, people see “CMS” as being synonymous with “blogging software”. They approach Pico thinking it’s gonna be Wordpress Lite or something, and get upset when it doesn’t have certain blogging-related features out-of-the-box or when the defaults don’t work the way they expect. I think me and @PhrozenByte are both guilty of quoting this line more than we’d like. 😅 It just gets a little old sometimes. 🤷🏻♀️ Pico works for all websites, it doesn't force you into a blogging platform if you don't need one. But at the same time, since it's not built around blogging, it takes a little patience and understanding to make a blog with Pico. I feel like I'm being mean or petty whenever I find myself quoting this though. 😔 Just come into it with the right expectations: Pico does whatever you want it to do, but some work on your part may be required. 😉 |
|
If you want to restore this PR too, you can do so by re-creating the |
|
So that's why that branch still existed... 👀 I literally deleted this one because it was so old and out-of-date. Anything useful from it had already been incorporated into my newer work. Anyway... idk, I'm not too bothered by these PR's getting closed. I'd prefer keeping things organized to restoring the old branches just for the sake of the PR's. Also, this one arguably should never have been a PR anyway, as it was really more of an Issue than work that would ever be ready to merge. 😓 |
This PR is a continuation of the ideas in picocms/Pico#359. With the new website repo, this needed a new PR, not to mention that it shares no code with the original branch I was using.
For quicker reference, here is the relevant content from picocms/Pico#359:
These WIP pages contain commented sections at the end that are from their original incarnations in the Docs. This is content that I've cut from the page and/or not yet reworked.
The current WIP state can be previewed here: