docs: New user tutorial #221

[klfoulk16]

docs: Create outline for new user tutorial.

[klfoulk16]

I've been trying to tidy up my commit history as it involves lots of commits for typo fixes and such...this has caused me to have to force push my branch. Is this the right way to do this? I feel like I'm doing something wrong here.

[chrisbobbe]

Thanks, @klfoulk16! I've just used this guide to get acquainted with zulip-term, and everything worked!

@pilgrim2308 has already mentioned the few typos I noticed.

Also, I'd second @neiljp's idea to squash all these commits into one; it's probably what I'd do in zulip-mobile. It's sensible to use separate commits while working on it—I see that they represent progressively complete drafts that all lead to the final draft—but I expect future developers reading this file's history will be much more interested in the work as a whole, than in the progress marked in each non-final draft. 🙂 What do you think?

[chrisbobbe]

Press ctrlf and a list of potential recipients will appear in the footer (highlighted in red).

I ran into an issue where this list didn't show up; the footer just stayed like this:

But then I saw a recent discussion on CZO and thought I'd try grabbing the app from current main (instead of the latest released version) to see if the issue was fixed…

…and it was! 🎉 So, no problem here.

[chrisbobbe]

Also, today I learned that you can use <kbd>x</kbd> and GitHub will render something that looks like a keyboard key: x. Neat, thanks for that!

[neiljp]

Do you think it's OK to have the tutorial be consistent with an unreleased version, then?

[chrisbobbe]

Do you think it's OK to have the tutorial be consistent with an unreleased version, then?

Hmm, good question. For purely ZT-developer-facing documentation (which is most or all of zulip-mobile's documentation, I guess), I wouldn't hesitate, because it's a safe assumption that developers are working on the latest main or at least can get there pretty easily (I used the Installation -> Latest part of the README).

zulip/zulip.git keeps plenty of user-facing documentation, so I looked there for some clues. I see a few commits (zulip/zulip@160cc5120, zulip/zulip@1d5aa2e51) where some functionality changes, and the user-facing doc is updated simultaneously. So, for some time, the user-facing doc on GitHub is inconsistent with any released version.

…but this turns out to not be a problem for that project, because the most natural way for a user to access the doc isn't through GitHub, but through the Zulip installation itself, where, if all goes to plan, the documentation will be precisely aligned with everything else. E.g., for CZO, you'd go to https://chat.zulip.org/help/; or, for the Recurse Center, https://recurse.zulipchat.com/help/.

In ZT's case, GitHub is the place a user goes for user-facing documentation like this tutorial, and GitHub naturally shows the latest code, which is often unreleased. Hmm.

I guess I don't have a definite answer. I suppose one solution would be to point users to a published website for user-facing documentation, and have it default to the latest stable release while allowing them to select something else. Like React Native:

But that seems like a lot of effort.

[chrisbobbe]

Also, I guess, the more frequently releases get made, the less one has to think about an inconsistency like this being a problem.

[neiljp]

Other thoughts:

• the released version could link to version of the doc at a particular commit/tag (release)?
• we could include the docs/ folder in the release?
• the tutorial could even be accessed in the application - though images wouldn't work (text snapshots could be interesting)

[chrisbobbe]

Ah, I almost forgot—along with the link to CZO (chat.zulip.org), I think it'd be good to link to the CZO community doc, which has lots of useful information that we'd like people to be aware of.

[klfoulk16]

Added the plug in the first paragraph

[klfoulk16]

Thanks for all the comments! I went through and fixed everything. As for the autocomplete...I left it in the tutorial but I made clear that you need to be using the version from Github (as opposed to the stable release). I also added more information about how to send PMs other ways.

[neiljp]

@klfoulk16 I've left quite a few points, thought these are not all directly applicable to the document/PR itself. I think this will really help people get started 👍

[neiljp]

These feel like two parts of the same feature - starting a private conversation with someone new?

[klfoulk16]

You mean the "Send a PM" and "Send a PM with the New Autocomplete Feature" sections? I do I feel like we could get rid of the "Send a PM with the New Autocomplete Feature" section as it is a bit repetitive. It could be better suited as a mini tutorial to explain how to use new features? If we removed this section it would also resolve the issue of potentially having to link the tutorial to a release.

[klfoulk16]

I think that linking to the tutorial somewhere in the help menu or maybe have a keyboard shortcut that opens the tutorial could be a good idea?

[neiljp]

You changed this now, but yes I think I meant those two sections felt like one section.

I think we should handle the tutorial/release synchronization issue separately.
Is your last comment regarding my response elsewhere in the PR about using the tutorial source at run-time?

[neiljp]

Mini 'feature tutorials' could go in the FAQ document, and we could link from the README and maybe at the end of the tutorial to a list of "things you might try exploring next"?

[klfoulk16]

Yup my last commend was in regards to your response elsewhere in the PR about using the tutorial source at run-time. I'll link to the FAQ at the end. I think for now the section about sending a PM can stay in this tutorial, I think it flows well.

[neiljp]

Other thoughts:

• the released version could link to version of the doc at a particular commit/tag (release)?
• we could include the docs/ folder in the release?
• the tutorial could even be accessed in the application - though images wouldn't work (text snapshots could be interesting)

[neiljp]

Not pertinent to the tutorial right now, but do you think we should support this working in the stream or topic list?

[klfoulk16]

I do feel like it's a bit confusing how it works in the middle column but nowhere else. Considering how the c key isn't repurposed for something else in other sections, I think it would be nice if the c key was consistent across ZT

[klfoulk16]

I decided I should remove the extra information about reactions and keep it short and sweet (the extra text was fairly verbose and intuitive)...let me know if you disagree and I'll add it back:

Reactions for a message will be displayed right below it, such as the "thumbs-up" reaction in the screenshot below. The number beside a reaction is the number of people who sent that reaction (currently it's 1). The fact that the reaction is highlighted pink means that we sent that reaction. The colors of reactions sent by others will be inverted (notice how the text is pink and the highlight is none for the reactions "octopus" and "+1" a few messages down).

[neiljp]

@klfoulk16 This is looking really great 👍

We could iterate on variations to the text, but this seems very close to ready. Some of the things that stand out for me are:

• Making the images more polished - mostly as we discussed. The smaller images already help, and when the text in them is larger (ie. fewer rows/columns) then that will too. I mentioned whether you want to use a demo/bot user for the screenshots in the stream. Also I wasn't sure if you had particular refinements planned regarding the annotations - do you have multilayer images which you're converting to the final versions, to explore different annotations? I don't think we need particularly polished versions initially, particularly if we have the originals to work with.
• Adding some emphasis on signing up for an account on chat.zulip.org (or some other server) early on "Ensure you have an account / sign up", to ensure the "learning by doing" can take place, given that users can't sign up using zulip-terminal yet.

Other than that, you've resolved some comments - but I'm not sure if the related version is pushed to the PR branch yet? eg. regarding one title level, the verb/noun splitting, etc.

I'd like to get the next iteration out for external review again, as it'd be good to hear from new users' :)

[neiljp]

It may be worth noting the equivalence to the sending key, or that may be confusing?

We could briefly mention that this (and deleting) normally leave the previous edition(s) available (with a potential link to "extra things to explore - message info -> edit history"?)

[klfoulk16]

Interesting, I had no idea there was a way to view previous versions of a message. I see a tutorial for how to do this on Zulip, but is it possible to do this on ZT? Right now I've linked to the Zulip tutorial about it. I think explaining how is outside the scope of this tutorial

[neiljp]

Yes, we support this right now with i on a message, and if there is history you can show that using e.

[neiljp]

@klfoulk16 We're discussing the images still, but I think we're good to get more feedback?

@chrisbobbe Would you be up for taking another look, if you haven't been following along?

Follow-up work that comes to mind: (please chip in with other ideas if you have them!)

• Add FAQ entries like "Can I see the past versions (history) of a message?", "Could you explain what reactions are and how they're displayed" (like the extra text above that was cut), and various similar aspects, so we can show more bullet points at the end of the tutorial.
• Simplify where we can use c (related to Improve compose hotkey behavior (as compared to replies) #871), allowing the tutorial to be simplified :)
• Linking to the tutorial doc at runtime (we'd have to figure out how to render it, unless we just link to a github page)
• Rather beyond the direct scope of ZT, but whether we can store screenshots as colored/positioned text, maybe via asciinema, to allow integration into the application, presentations, ... (generalizing to add captions)

[chrisbobbe]

Thanks, @klfoulk16!

Would you be up for taking another look, if you haven't been following along?

Sure!

I've just gone through it again, and overall it still looks great! I've added a few small comments below (sorry if some of the points already have discussions that I missed 🙂).

[chrisbobbe]

nit: Is there a reason to put a space between "#" and the stream name, as in "# test here"? I'm used to there not being a space there, but I see the space has been used several times, including in at least one of the images.

[klfoulk16]

I guess I always felt like there was a space there (kinda looks like it in the desktop app and ZT). I think the person who originally started this tutorial had a space there so I continued that syntax

[chrisbobbe]

You can edit the message's content, topic or stream.

Huh, interesting; @neiljp, when it says you can edit the stream of a message, is this the relatively new "move topics between streams" feature? Hmm, but IIUC #826 suggests that that feature isn't yet fully handled. So I guess I'm not totally sure what's meant to happen if you edit the stream. 🙂

As one data point, I tried editing the stream of a message in #test here, so its stream would instead be a different one, a private one I had made months ago for some testing.

I confirmed in the web app that the message remained in #test here, and no new message appeared in the private stream. The message's edit history in the web app looks like this:

[klfoulk16]

Ready for review!

[neiljp]

@klfoulk16 This looks great! I've left a few points, but really they're just polish which we could add later.

We can move the developer notes at the bottom into a markdown comment right at the top of the the document?

We didn't get a conclusion on the space in '# test here' though?

I'd be happy to hear from @chrisbobbe again, or others, or look to merge :)

[klfoulk16]

Tackled all your comments and fixed the odd # test here space. I think it's ready!

[neiljp]

@klfoulk16 Thanks again for all your work on this! I pushed a slightly updated version temporarily to https://github.com/neiljp/zulip-terminal/blob/review-original-922/docs/getting-started.md - you can check the latest commit there for the few changes I made on top, but other than some minor textual changes, the biggest net effect was using pngcrush which losslessly reduces image size by ~75%!

This is in my merge queue based on that version, so let me know if I've missed anything or you have any last-minute thoughts :)

[klfoulk16]

I just read through it and everything sounds/looks great! That's awesome you were able to compress the images that much! I should have thought of that.

[neiljp]

@klfoulk16 Thanks again! Merged 🎉