search

textpattern / textpattern

A flexible, elegant, fast and easy-to-use content management system written in PHP.
https://textpattern.com
GNU General Public License v2.0
776 stars 111 forks source link

Rework the default article #1574

Closed petecooper closed 3 years ago

petecooper commented 3 years ago

Our default article is a wall of text.

We should investigate making it much simpler, clearer and easier for a newbie to understand. From a maintainability point of view, it will make localisation much more straightforward and sustainable.

Considerations:

@philwareham - what's on your shopping list?

philwareham commented 3 years ago

What's on your shopping list?

The absolute bare minimum, in my opinion. To borrow from a lesser-known CMS, as an example...

Welcome to WordPress Textpattern. This is your first post. Edit or delete it, then start writing!

😁

Maybe not that succinct, but you get my drift.

petecooper commented 3 years ago

Funny you say that, I'm inclined to do a blank sheet rebuild rather than edit the current text. The extra stuff could be the barebones of a .com/docs "next steps" landing page that opens in a new browser tab.

bloatware commented 3 years ago

Don't ask me to translate it again, unless it fits into 10 words!

philwareham commented 3 years ago

Don't ask me to translate it again, unless it fits into 10 words!

Yes, exactly! The large welcome article is a pain to get translated. And if anything changes (which things do, in the current welcome article) then it means a re-translation. Shorter the better in my opinion.

Bloke commented 3 years ago

Shorter the better with a link to an online 'next steps' doc gets my vote. Don't we have one of those already that we can repurpose? I thought zero wrote one, which we eventually distilled to the one that's now in the default article? Might have been on the old docs wiki and got lost/recycled in the transition.

philwareham commented 3 years ago

Can you possible suggest some text Stef? As our master wordsmith!

Bloke commented 3 years ago

Sure, I'll get onto it and fashion an article on the docs site over the next day or so.

EDIT: Or do you mean for the Txp article itself?

petecooper commented 3 years ago

OK, so we're largely agreed that it's a bit unwieldy right now and the pointer to a docs landing page seems like a straightforward thing to do.

This is not massively urgent. Given we have 4.8.4 coming out in three-ish weeks, I think we can definitely wait until after that. We'll need to:

Edit: no longer relevant, but left for completeness.

What else?

@Bloke - I can help with this if you want additional eyes and brainz.

philwareham commented 3 years ago

I'd suggest that changes to the 'welcome' article are made in the localised-setup-content branch (which I've just synced to latest dev branch snapshot). Once we have something we're happy with I can move the translation file over to Crowdin and get translators onto updating their versions. Cheers!

Bloke commented 3 years ago

At the risk of regressing on what we currently have (which is, as @bloatware says, unsustainable as features are added) I don't think we should translate the docs landing page. Docs are English. We don't have the people power to keep multi-lingual docs up-to-date.

The new default article content can just be a few simple lines, as Phil suggests. A placeholder with nothing specific so we're not making work for ourselves / translators. We can use the linked English doc page as a springboard / dashboard - with orientation info on terminology, and links to a few other docs such as managing themes, plugins, general admin techniques, and so forth.

I see Pete has started a thread about docs curation so we should definitely use this to polish up the docs and maybe get the https://docs.textpattern.com/index2 made live.

We also need to revamp all the tag pages to use the includes for global attributes (see the section_list tag for an example). I was holding back on doing that until we'd further investigated self-hosting docs, but maybe we should start now, since it'll be a bit of a chore.

petecooper commented 3 years ago

Docs are English.

Yep. I've updated https://github.com/textpattern/textpattern/issues/1574#issuecomment-722563002

philwareham commented 3 years ago

I don't think we should translate the docs landing page.

Agreed, it is not my intention to translate any of the docs site, not even a landing page directed from the welcome doc.

petecooper commented 3 years ago

I'd suggest that changes to the 'welcome' article are made in the localised-setup-content branch (which I've just synced to latest dev branch snapshot).

https://github.com/textpattern/textpattern/blob/localised-setup-content/textpattern/setup/default-content/en/articles/articles.welcome.xml

Bloke commented 3 years ago

How about this as starter content? The link to the docs site can be to the 'orientation/getting started' article rather than just the base URL.

Refine at will:

Body

Welcome to Textpattern! This is your first post, which you can edit or delete and then start writing your own content.

If you're new here and would like a quick tour then please see Textpattern in Two Minutes or head over to the docs for more detailed information.

Have fun!

Excerpt

This is a an excerpt for the welcome article.

Article excerpts are optional and can be used to summarize an article's content for display on article list pages or as opening teaser paragraphs.

petecooper commented 3 years ago

@Bloke - can you work that into https://github.com/textpattern/textpattern/blob/localised-setup-content/textpattern/setup/default-content/en/articles/articles.welcome.xml so we can tweak, please? Thanks!

Bloke commented 3 years ago

Done in c165b79dc.

philwareham commented 3 years ago

I'm happy with this. Feel free to make any minor amends though as you see fit. The length is good now though, so no extra text needed IMO.

petecooper commented 3 years ago

+1 from me, much better. Thanks, @Bloke and @philwareham! A few too many words for @bloatware to translate, so he's escaped this time…

Can we merge into 4.9 if @Bloke is OK with wording? This can be closed when that's done.

philwareham commented 3 years ago

The branch can't be merged into 4.9 as yet, because the whole code around localised default content isn't written yet I think?

You can certainly cut/paste the text from the file above into 4.9 branch's equivalent file though, manually.

philwareham commented 3 years ago

@bloke Shall I update Crowdin with this new translation? It doesn't affect 4.8.4 development since that file is not used at all in 4.8.x.

petecooper commented 3 years ago

You can certainly cut/paste the text from the file above into 4.9 branch's equivalent file though, manually.

Good enough!

petecooper commented 3 years ago

(OK, now I'm done fiddling.)

philwareham commented 3 years ago

Great! I have now moved the translation over to Crowdin for our translation gurus to action. Happy for you to close this issue when you are ready.

petecooper commented 3 years ago

You can certainly cut/paste the text from the file above into 4.9 branch's equivalent file though, manually.

With the risk of looking a bit dense…what branch is that? dev?

philwareham commented 3 years ago

Yes!

petecooper commented 3 years ago

Done.