Restructured upgrade.md

[mayamcdougall]

Restructured upgrade.md to be more readable. It's still a work in progress, and the content needs to be refined a bit more.

[mayamcdougall]

I think the toc might be a little screwed up a the moment as well. Only some of the items were working properly for me. I'm not yet sure what the issue is. Anyway, it's a work in progress as I said, so I'm mainly looking for feedback on the new structure. I'm still working to refine the actual text where needed.

Also the broken images are from @theshka's original content. I don't know if he's got some images for it, if I should make some, or if they should just be removed.

[PhrozenByte]

Screenshots shouldn't be necessary, the process isn't that complex. Furthermore, performing an update by deleting single files (i.e. cleaning up a existing installation) is extremely error-prone! That's the reason why I decided that users should backup their files (it also forces users to create a backup...), install Pico newly and apply their customizations (i.e. config, contents, themes and plugins) to this clean installation. Please note that the contents which are currently commented out are older than the currently visible contents!

Unfortunately I even don't like the new structure, the reason behind splitting the page into two separate and equally entitled "How to upgrade" and "What's new" sections was, that this way a user understands at first glance that he has to read just the "How to upgrade" section to know what he has to do. With your suggestion he is also required to read the "What's New - Changes for Users" section - as a user, I wouldn't expect this and it probably results in many Issues like "Why is {{ page.excerpt }} not working anymore?" and "disabling URL rewriting doesn't work".

Please see the second paragraph of my comment in #268.

[mayamcdougall]

I agree, I don't think screenshots are necessary they were just already there. I'll remove them.

I agree about the installation method. Both methods were in the file, however this one was worded better so I used it as a base. I'll rewrite it using the "delete everything" method.

I think we have differing ideas of users, and I don't know which one is more accurate. When I picture a user, it's someone who has chosen Pico to make an easy site for displaying content. They likely have downloaded a theme from the wiki and are not that interested in making their own. They would treat themes as they would plugins, like self-contained entities that they wait for the developer to update.

So, when I imagine what a "user" wants to know about updating, it's what I've put in the "How to Update" section. Simple, concise instructions, that don't overwhelm them with details. If I knew nothing about how themes worked and I saw update instructions telling me about how {{ page.excerpt }} doesn't work anymore, it wouldn't be helpful.

That was my logic anyway. And I guess by that logic, I should have called it "For Developers", which would be further from what you're looking for.

Your idea of a "user" however is what I would consider either a "power-user" or on some level a "developer". Someone who wants to know the gritty details of how things have really changed. Someone who writes or customizes their own theme. Someone who would likely gloss over the first section and jump right into the "What's New" section.

Now, given the fact that this is web design and administration we're talking about, I'll give you credit that the user-base probably does skew in that direction, and you'd know better than me.

Food for thought though, as a "php developer", you see anyone who doesn't touch the php as a "user", while as a "theme developer", I see anyone who doesn't touch the theme as a "user". 😕

So, what would you like to see done with this? I could make the "What's New - For Users" section into more of a "Update Details" while the "Under the Hood" becomes just "What's New".

I've been previewing it with the site's styles as opposed to GitHub's that way I can get a better idea of what the finished content would look like.

My main focus is to try to bring this file up to the quality and readability of the other Documentation. I want it to be approachable by anyone (casual user, power-user, or developer) and not feel overwhelming.

Please note, I've been trying to follow your guidelines as best I can. I think the issue is more this difference of philosophy I've described than a difference of opinion about the structure.

I'll try again to head in the direction you've suggested, but with an "everyone's a user" mentality instead.

[PhrozenByte]

Yeah, you summarized pretty well what I personally see as a "ordinary user". However, @theshka and @picocms (and others) don't necessarily share my opinion 😄

Maybe we should go with your idea of having three distinct and equally entitled sections. The first section addresses everything a "I'm neither creating custom plugins nor themes"-user needs to know, the second section addresses everything a "I have my custom theme"-user needs to know and the third section includes the "under the hood" changes. The latter will be extended by the dev docs (_plugin-dev/upgrade.md). I don't know how these sections should be named (neither "How to upgrade" nor "What's new" fit...), maybe someone has a good idea...

Ensuing from the old upgrade.md (this one), the first section is basically the "How to upgrade" section without its sub-sections plus the "Ensure restricted access" section and the part of the "Routing system" section talking about Markdown files. The second section basically consists of the remaining contents and the other half of the "Routing system" section. The third section needs to be added.

Do you think this is a good plan? 😃
btw @theshka, what do you think about this?

#edit: btw, do you know that GitHub automatically deploys your changes? You can find them here: http://smcdougall.github.io/Pico/upgrade.html (internal links are always broken, you must change the URL manually to navigate to different pages)

[mayamcdougall]

Actually, I didn't even know the upgrade page was live on the website... 😒 Apparently it needs a more prominent link... or I need to be more observant. As far as the GitHub thing goes, I did get an email earlier telling me that the name "picocms.org" was already taken, lol. I was wondering what that was about.

Although I like the elegance of having two sections, I've been staring at this document all day and there's just so much information. There's definitely three distinct sections, but I think I've thought of a solution.

The general update information really is redundant. Why not just remove it altogether and replace it with one line a link pointing back to the Upgrade section of docs. I'm thinking maybe the Upgrade section of docs should be revised a little bit. There's nothing really wrong with it, and it sounds okay, I just think it should stand out a little more. I'll let you know when I figure out what I mean by that... I just feel like it needs... something.

Back to upgrade.md. With the regular "How to Upgrade" steps removed, the page could just focus on the specifics. "How to Upgrade" would be just the advanced update stuff, while the remaining "Under the hood" would become "What's New".

This would keep the simple instructions clean (as they're on the docs page, where they should be), and keep the page focused on just the advanced, 1.0.0 specific, upgrade instructions.

[PhrozenByte]

Sounds reasonable, I look forward to your concrete suggestions 😃

[mayamcdougall]

Sorry for the messy commits. Not sure how to clean them up, and my attempt at reverting didn't work so I just "pushed" a copy where I had undone the last two commits.

If there's a way to clean up the history (if it even matters) before finalizing this page, let me know and I'll do it.

[mayamcdougall]

Alright, now it's where I wanted it to be at the first commit this morning. 😒

@PhrozenByte Any thoughts about this layout? Also, is there an easier way to get to the rendered page besides typing in the url? I was poking around but couldn't find one.

[theshka]

To be completely honest, I feel like this is too many "upgrade/how-to" sections. I think we are all mostly together on this; however, please let me know if I'm missing the point of #268 (comment) + entirely @PhrozenByte @smcdougall ... Both the _docs/upgrade.md page (which is fine how it is) and the (still needed) _plugin-dev/upgrade.md page (currently the info is in /plugin-dev.md) sections should point to /upgrade.md.

---

Inside that single /upgrade.md page, sections should be divided in to:

• How to upgrade

  Usually you don’t have to consider anything special when upgrading a existing Pico 0.8 or 0.9 installation to Pico 1.0. You basically can follow the regular upgrade instructions as if we updated the MINOR version.

  1. Create a backup of your Pico installation. You will need the files later!
  2. Empty your installation directory and install Pico ordinarily.
  3. Copy the config.php from your backup to config/config.php. You don’t have to change anything in this file.
  4. Copy the content folder from your backup to Pico’s installation directory. As a optional step, you can (but aren’t required to) make your content files compatible with Pico’s new routing system. You’ll find detailed instructions on how to do this in the “Routing system” section below.
  5. If applicable, also copy the folder of your custom theme within the themes directory of your backup to the themes folder of your Pico installation. Again you can (but aren’t required to) make your theme compatible with Pico’s new routing system.
  6. Provided that you’re using plugins, also copy all of your plugins from the plugins directory. Don’t copy the plugins/pico_plugin.php - this is not a real plugin, but Pico’s old dummy plugin.

• What's new

  • ...for users (we already have this, notwithstanding our slight difference in definition of a user. It's basically an expanded version of Pico 1.0 #252 (comment))
    • Initialization
    • Routing System
    • Drop of {{ page.content }}
    • Drop of {{ page.excerpt }}
    • Ensure restricted access to content directory
    • Plugin System
      • Backward Compatibility
    • Further Reading
  • ...for developers
    • why doesn't it just point to the changelog?
    • link to the class documentation

---

Then in _plugin-dev/ keep it simple and use the same language as with the above "What's new ... for users"

• Basics
  • Core
  • Plugins
  • Your First Plugin
• Upgrade
  • Migrating 0.X -> 1.0 (the most imperative notes for upgrading a plugin)
  • Link to /upgrade.md (...for users, ...for developers)
• Plugin Wiki

---

At the end of the day, we are on GitHub, I would suspect that any "user" who is going out to find a framework for generating websites from markdown files is a) pretty niche, and b) is already somewhat familiar with programming.

Otherwise, why not just keep the instructions dead simple-- remove all mentions of #252 comment, class methods, and "nitty-gritty" changes... This would be for someone who doesn't know anything about programming whatsoever at all, and point all "power-users/developers" to the #252 comment, the changelog, and the PhpDocumentor class documentation?

---

p.s. @smcdougall why don't you just install the Jekyll gem and run the changes you make locally before pushing? That's probably the easiest method... also look in to git rebase for cleaning up commits, and git reset, git checkout, or git revert commands for restoring your working tree to another point.

one more thing, all of your anchor tags in the upgrade.md do not work, you need to define them like this:

This is my link's [DisplayText][IDtoURL], and I will add the URL

...later in the document, on it's own line, with nothing in front of it.

[IDtoURL]: http://url.tld/

[mayamcdougall]

@theshka I don't know... The more I've been thinking about it, the more I like the idea that this should be a dedicated document about the transition to 1.0. The general upgrade instructions are the same as any release, so including them seems redundant.

By removing them, it gets right to the point. Plus, users likely already know the upgrade process, it is dead simple after all.

I wouldn't be entirely opposed to bringing the plugin-dev instructions into this document though, if only for the sake of having one upgrade document.

Thanks for the tip about the Jekyll gem, I'll probably grab that later. I was trying to use HarooPad to roughly preview the site styles, but it only shows the Markdown content and not the rest of the page. I don't care for the program though and it was partially to blame for all the toc commits. Once I switched back to Atom, I realized right away that I'd screwed up the toc indentation. Atom + Jekyll will probably be my workflow going forward.

And sorry about those links at the bottom, I thought they were broken. I didn't realize that's how it was defining them.

(I tried to send this reply multiple times from my phone... if a duplicate shows up later, that's probably why).

[mayamcdougall]

@PhrozenByte Sorry, didn't get the time to work on this that I'd hoped for. New structure, as you suggested. Added an "Additional Information" header between the general instructions and the more advanced information. I don't like calling it "Additional Information", so let me know if you have a better idea. I just thought it should be separated from the steps slightly.

Also, I realized something while reading through this for the billionth time. The general instructions suggest that a users could copy their custom themes back into Pico, however this would likely break without enabling PicoDeprecated due to the lack of page.content/page.excerpt. Unless they are also using an old plugin, PicoDeprecated won't be automatically enabled just because they're using an old theme. Maybe there should be a note or other instructions for accomplishing this? What do you think?

https://smcdougall.github.io/Pico/upgrade.html

[theshka]

I'm sure @PhrozenByte took care of that little caveat in 2a43b21 @smcdougall, I'll take a closer look at the rest here soon too :)

[PhrozenByte]

@smcdougall: Yes, a short hint about the "Drop of {{ page.content }}" and "Drop of {{ page.excerpt }}" sections in Step 5 is reasonable, just like we do it in Step 4 for the Routing System. I'll take a closer look in the next days, but it seems pretty good at first glance 👍 😃

[mayamcdougall]

Any other suggestions for this file? The link to .htaccess is broken because I changed the gh_release to v1.0.0, not sure what to do about that. I also want to go through and standardize the capitalization of some of the links.

When referencing another section (eg "see [Routing System]"), should the link use Title Case like the header it's referencing or be lower case like the rest of the sentence? It's inconsistent throughout the document right now.

[theshka]

I think, grammatically, it should be in Title Case to match the headings @smcdougall... The inconsistencies are not there on purpose 😆

It should also be noted (and has been fixed most places) that "Pico" is a proper noun. It should always be capitalized, and when talking about Pico in another context; it should be possessive and not plural (i.e. "Pico's", not "Picos")

[mayamcdougall]

I'll look it over for any "Pico" inconsistencies, but I would have fixed those already if I'd seen them. 😉

I thought of the Title Case issue when I realized I'd written "For Theme Designers" on one link and "for theme designers" on another. I never know what to write for links. It's always hard to avoid the urge to just write "click here". 😆

[mayamcdougall]

Hmm... I added more backticks to some of the code-oriented links (eg [`Pico::setConfig()`] , matching some that were already formatted like that. It makes almost no difference under the site's current style to have them formatted as 'code' though, so I'm thinking I might just remove them all. It made sense at first that regardless of them being links, the code should be highlighted. Now I just think it makes them harder to read though. Thoughts?

Also, it feels just about ready for deployment, minus maybe adding additional "What's New" items.

[mayamcdougall]

Yay! 😃

[mayamcdougall]

@theshka FYI, that .htaccess link is still broken.

It uses {{ page.gh_release }} which I changed in the header to be 1.0.0. I wasn't sure whether to just rewrite the link to reference the master branch or how you guys would want to proceed with it. If you want to change it, the link is at the bottom of the file and reads:

[RewriteFile]: {{ site.gh_project_url }}/blob/{{ page.gh_release }}/.htaccess#L7

[theshka]

Thanks @smcdougall, @PhrozenByte took care of it in 2aa5711 👍

@ALL: I also rebranded the picocms.org stylesheet to match Pico's default theme in 8deb744