Working on a reviewer's guide for 1999.io

[scripting]

This isn't a traditional "issue" but it kind of fits.

I'm working on a new howto doc using Fargo -- it's a reviewer's guide for 1999.io.

http://reader.smallpicture.com/?opmlurl=https%3A%2F%2Fdl.dropbox.com%2Fs%2F09kyskkucmtgml9%2FreviewersGuideFor1999io.opml%3Fdl%3D0

I've started to list the most important ways to pick up the software. I wanted to be respectful to WordPress, Blogger and Tumblr, but it's important so show how 1999.io is different, and in many ways more advanced.

[akaKenSmith]

I like the reviewer's guide. Occasionally I felt it might be underplaying the strengths of the software, too mild or modest, and so I pasted it into an outliner and tried to tinker a bit, to amplify a bit. If any of the rewordings are useful, great, but if not, no harm done. I liked thinking about the software and enjoyed the chance to do it. Here is the link to the outline.

http://reader.smallpicture.com/?opmlurl=https%3A%2F%2Fdl.dropbox.com%2Fs%2Fqasdz199n6y1gt3%2Freviewdraft.opml%3Fdl%3D0

Ken

[scripting]

Ken, a reviewer's guide is not an ad.

It's an old idea back when people did software reviews. You'd provide the guide along with the product to reviewers so they knew what you wanted them to consider.

They were just suggestions, and if you hyped them, they'd trash it. And might even trash the product.

I still produce them for products, mostly so I know when I'm talking about it, these are the main points I have to hit. It's a way to get my act together.

No one needs to be sold here. That comes later, and in different contexts.

[akaKenSmith]

I see now, thanks, and since my posting goes down the wrong path, maybe it is a distraction that we should delete here?

[scripting]

No no no. It's fine. We're all friends. ;-)

[scripting]

Scott Hanson says via email that ease of installation is a major benefit.

I think he's right. So I've added a bullet item under "For programmers..."

• [ ] Quick install. Less than 5 minutes.

Dave

[akaKenSmith]

A small thing...I keep rereading that part that says "a few simple obvious steps" and I think, yes, but even that word "few" seems to make it sound harder than it is. For a basic post, type in the box and click Post. That's it. I think of an old posting, probably on Scripting News, about how many steps it takes to post something in the blogging software of a decade or more ago, and now here we are at two steps.

[Aside: until there's a blogging tool that uses telepathy will we ever see one-step posting? Maybe there could be code written that takes the first character typed as a command to post the contents of the composing box, and that would be one step blogging, but for now, two steps seems to be the natural limit and it has been reached here, happily.]

[scripting]

Ken, I agree and it's not a small thing.

It's done. Have a look.

[scotthansonde]

"No web server or database needed."

[scripting]

We cover the database stuff.

Isn't it a detail that no web server is needed?

And doesn't it raise questions if you're already running a server and want to run 1999 behind it?

Not sure about that one.

On Sat, Jun 4, 2016 at 12:21 PM, Scott Hanson notifications@github.com wrote:

"No web server or database needed."

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/scripting/1999-project/issues/27#issuecomment-223764338, or mute the thread https://github.com/notifications/unsubscribe/ABm9OzcOQAbkBXYMXZVoVjmFgytqn5NYks5qIaYCgaJpZM4Isp0M .

[scripting]

BTW, I figured out a really nice way to incorporate screen shots.

Look at the section with the new-post stuff.

http://1999.io/about/

[scotthansonde]

OK, then leave it out. That it runs on node should be a hint about that anyway. :-)

[akaKenSmith]

That image works well there, I think, and illustrates the text above it instantly for a newcomer. Still waiting on the telepathy control system here, though.

[scripting]

I had left out any mention of the AWS version.

http://blog.1999.io/2016/05/07/0020.html

It's now included under installation bragging.

We really need an easy Docker install.

[akaKenSmith]

Maybe for newcomers say "As easy and familiar as writing a tweet or a Facebook post."

[scripting]

Ken I think that goes without saying. The words tweet and Facebook are familiar themselves.

[akaKenSmith]

The revisions this morning are leading to a really clean direct style in the newly revised parts. If you'd like suggestions about that kind of thing at this point, I have a couple also. It may not be what you're focusing on today, though.

[scripting]

Ken the feedback today is great. Keep going.

[akaKenSmith]

[Lots of judgment calls here, take what you like, I won't be offended.]

"get started with" seems just off-key to me since composing in 1999.io is always simple, not just at the start. And if the revisions are leading to tighter phrasing, I keep tinkering with the opening sentence. Current version is this: 1999.io is easy for writers to get started with, is completely customizable by designers, and can be extended by programmers through easy APIs and full access to the server code.

Suggestions are in here, bold so you can see them: 1999.io is easy for writers from the start, completely customizable by designers, and extendable by programmers through easy APIs and full access to the server code.

[akaKenSmith]

This doesn't, to me, quite have the directness and sharpness of the other sentences in that section:

Other blogging software can be hard to navigate for writers who want to quickly record an idea and get back to what they're working on.

Maybe something more concrete? Eg.:

Writers spend their time composing, not navigating the steps and layers of older blogging software.

[scripting]

Re "Other blogging software can be hard ..."

It's written that way deliberately to focus on the other blogging software, not 1999.

I want the heads to be nodding there, because they know what I'm talking about.

Dave

[akaKenSmith]

My concept here is that when revisions are streamlining nicely, once in a while they get sort of a little too telegraphic, too compressed, and a small return of clarifying language can make it sound lively and active again.

The template editor is just a menu command away. No programming required. Make a quick template change in an instant. A second command rebuilds all your pages.

[akaKenSmith]

Almost everything in the current version seems clean and sharp to me upon rereading this afternoon. This sentence feels like it would ordinarily have an example or two attached to it, but maybe that would be too limiting: This opens up new applications for blogging that aren't possible with static-only blogging tools.

[scripting]

BTW, I included the startup video in the first section.

Ken, keep the comments coming, I'm going to do another pass over the whole doc later today or tomorrow.

[akaKenSmith]

I just viewed the video, looks good. The only other writing thing that catches my eye right now is the heading for the Live section, with "Live" in quotation marks. Since a portion of the time people use quotation marks is in a mocking way, and it means "so-called but not really", I get nervous about the quotation marks there. It really is live, so why the quotation marks anyway? But I don't want any readers to get that negative tone there from the "so-called" thing. These pages are Live or Instantly Live or Always Live or something, but I don't think they're "Live" at all.

[roguish]

I am liking the reviewer's guide. 1999.io has great functionality and the guide makes this very clear. One small point. Why is the line about Facebook under the Podcast Platform heading?

We also support Facebook's new Instant Articles format.

To me that's a really important point. I got turned off Facebook years ago when I realised they wouldn't just let me write once on Wordpress and then syndicate. I just stuck with Wordpres but was aware most of the discussion was on Facebook. Now FB is starting to open back up, with RSS (!), there's a big opportunity. I'd like to use 1999.io to write once and publish in several places. Maybe that syndication capability would be something to note in the reviewer's guide. I think 1999.io could shine in this area.

Thanks!

[scripting]

I made a bunch of changes, tried to incorporate most of the suggestions here.

I also added the OPML file that it's generated from to the repository here, so you can spot the changes. Not in a particularly human-readable format, but it was the best I could do quickly.

https://github.com/scripting/1999-project/commit/1fca7c7cb48e2f58452614da8b0cb94c3bc7de4a#diff-ac88dc1a8e6022fdbe5834dd2d396a74

[akaKenSmith]

I read the About page a couple of times over the course of the day and spotted the various changes pretty easily. I think it's getting pretty tight all through. The "Other blogging software" sentence still feels a little abstract to me, compared to the streamlined precision of the rest, but it's a small thing and maybe not worth fretting over.

But I'll try to pin down what's bugging me. I seem to locate the abstractness in the phrase "hard to navigate." For someone used to, say, WordPress, as I am, it's not really hard, it's just too involved. It seems to me that there are just too many layers and steps, especially compared to 1999.io, for a person who wants to post and get back to work, which as a wording there in the second half of the sentence in itself has an appealing concreteness and down-to-earth quality. Would it be a little sharper with something like this?

Other blogging software can

be too clunky? be too detailed? have too many layers and steps?

for writers who want to quickly record an idea and get back to what they're working on.

But I don't think the current wording is bad--just not quite in the style of the rest.

[scripting]

I added permalinks to the page.

http://1999.io/about/#ubc

[cbasturea]

One (and only one) of features listed made me read the description to understand what it means -- "User-accessible backup command". Maybe something like "One-click backup & server move" would be more newbie-friendly?

[scripting]

I added a section for One-click Edit This Page.

http://1999.io/about/#oetp

[scripting]

I just linked to the About page in a tweet.

https://twitter.com/davewiner/status/740159557293510656

Here we go! :-)