28th MARCH - Reference Documentation

[LAP]

Hi All,

Attached is a draft of the reference documentation for Scrivener 1.0. For those willing to provide feedback on this document it is much appreciated. Thank you.

UserManual-Windows.pdf

(1.02 MiB) Downloaded 1318 times

[AmberV]

Quick note: this was produced directly prior to b21, and so does not contain fixes and adjustments to the list of new features and fixes in b21 itself. Since that's one of the main things I'm working on right now, chances are anything in the b21 changelog list will be fixed and there is no need to contact me about it. If there is some other error not in the b21 changelog, don't hesitate to post in this thread or send an e-mail to support with your notes.

[bta1701]

Page 25
Paragraph 2

There’s an apple key in the shortcut for Paste.

[AmberV]

Got it; thanks.

[SpirosD]

Page 9 (of document - page number 3)

3. Eventually, you may begin to see an order emerging and repin the index cards accordingly.

Maybe repin should be written as re-pin?

[SpirosD]

Oh, also maybe you should pick one variant of English and stick with it.

I've seen British "-sation" and American "-zation" words throughout. They're both correct, obviously, depending on where you live, but not in the same document.

(I've done this lots of times on submissions myself )

[MimeticMouton]

Oh, also maybe you should pick one variant of English and stick with it.

It should be British English throughout, with the exception of specific UI items. Computers use American English! Which can make for some funny reading, but the developer's British so by golly the manual's going to be, too.

That said, if there's American English outside of the menu item names, etc., it should be corrected to British. Give it more tea.

[Pellinore]

OK. I tried to read the whole thing. Got tired around page 100, but got to the end. It was cursory read at best. Looking for copy edits.

I realized as a long time mac user, I never have really read the manual like I read this one. I just did the tutorial and away I went. It was amazed at how much is under the hood that I knew through using the software, but seeing in "black and white" was enlightening.

OK here are my initial thought?
p. 18 scratch view for "Scrivenings view"; it's redundant.

at 6.2, an instruction for people to refer back to 5.1 would be helpful.

What is a "test-bed" project?

p. 36/37 I think a picture of the windows file structure would be helpful for n00bs and non-windows folks.
suggestion: change structure of 6.8 to 6.8 How a Scrivener File Works in Windows, then 6.8.1 shows the Windows structure, and 6.8.2 Difference between Macs and Windows

I love the examples for the use of collections. perhaps bullet point?

What is HUD? Where is it defined?

I saw a few links in the pdf. like the link to the software licence. Will there be other hypertextual moments, so people can click to go back to reference points?
Why I ask? Because it would be great to have a screenshot of a traditional Scrivener screen and then links to the various sections of the manual to go with your flow.

Overall I wish the manual flowed a little bit more like the tutorial. Not too much, just a bit more.

And I wish I had more time to give you, as I used your need of editing as an excuse to procrastinate my deadline for pages of my new play that are due tomorrow.

Love the software. Love this project.

Woo-hoo!
Pellinore.

PS. Here's a crew that uses Scrivener to make their projects: http://vimeo.com/15693382

[Pellinore]

I realized I should have copy edited my own post before sending. Really, I am an editor by trade as well. Just displayed a shoddy job of it. Hope my edits make sense.

[AmberV]

Maybe repin should be written as re-pin?

Fixed.

p. 18 scratch view for "Scrivenings view"; it's redundant.

Could you expand a bit on this one? This particular section of the manual is meant to be a cursory overview of the interface, cross-referenced to the full articles on these concepts where appropriate. Basically having this section up here gets some core concepts in early on, such as thinking of a long text in terms of small pieces you can stitch together at any time to read or edit.

I did comment out one Mac reference in this section though, so thanks for pointing it out.

at 6.2, an instruction for people to refer back to 5.1 would be helpful.

Actually, it looks like that section *did* link back with a figure cross-reference to the screenshot, in the Mac version. This link was mistakenly omitted in the Windows PDF. So good catch.

What is a "test-bed" project?

Fixed; it just states "old and unwanted projects..." now. I'm sure I had something clever in mind with that line at some point in time.

I think a picture of the windows file structure would be helpful for n00bs and non-windows folks.

Actually, it's not included in this pre-release, but I am close to finishing a documentation of the project folder, for the appendix. Once that is in place, cross-references will be placed in the appropriate places in the text.

As for pointing out the differences between formats---there really aren't any major things worth pointing out here (though certainly in the appendix). A few preference level files can be different---compile right now is one of those, but eventually this will no longer be the case. This is an interim solution due to the large differences in compiler capabilities right now.

The main visible difference is the .scriv = folder / .scriv = file thing, and learning how to open a project on both computers is going to be the most relevant for this section of the manual.

I love the examples for the use of collections. perhaps bullet point?

I think we must be looking at two different spots. The example list I'm recalling is in 7.4, pg 43---and it is in a bullet list already. There might be another list somewhere, and if so it ought to be consolidated into this one.

What is HUD? Where is it defined?

The first mention of the acronym, on pg. 53, in a footnote.

Why I ask? Because it would be great to have a screenshot of a traditional Scrivener screen and then links to the various sections of the manual to go with your flow.

It would probably be more trouble than it is worth. I'm not a PDF expert, so I'm not sure if the "image map" concept has an analogy, but even if it did it would be something I'd have to manually do each time I compile. I try to keep that stuff at a minimum, because I have to create multiple PDFs at a time, on a regular basis (generally each minor release).

If this were a finished product that I could put a "Done" stamp on and walk away from, maybe some manually applied polish like that would be nice, but that's not really something that is feasible for a software manual. It's got to live just as rapidly as the software it documents.

Overall I wish the manual flowed a little bit more like the tutorial. Not too much, just a bit more.

And here I was worried it did a bit too much of that.

I think I must respectfully disagree on the point that it needs more though. I think keeping the more tutorial-esque aspects and philosophical discussions in the beginning is good, but eventually you need to just get into the facts. Software needs a concise reference guide that describes features succinctly and by name, so you can look up something that confuses you in a menu and know what it does. If everything was in Tutorial Speak, it would require a lot more digging around and skimming if all you want to know is what something does.

Thanks again to all.

[JoGirl]

Not sure if this is the right place in the forum to mention this. I understand the need for a reference manual. Also the need for tutorials for new users in the form of videos. I don't know if there will be tutorials, but I am an advocate for them. I would separate the two, given there are tutorials, then the reference manual can be less "tutorial-ish", if that works better. Just my two cents.

[AmberV]

That's the idea. For educational material there will be:

• The video tutorials (in time)
• The interactive tutorial; accessible from the Help menu and definitely meant to be the way to learn the basics
• The user manual
• The knowledge base / wiki / forum

[sablebadger]

Just jotting things that jumped out at me while reading through it, most of these will be suggestions rather than major issues.

p.5 "Example: Alt- E which matches FileExportFiles..., means you
should hold down all two of these modifier keys,"

Change to "means you should hold down both of these modifier keys,"

p.7 "If it does not state that it is verified, you could be attempting to install an unauthorised copy from a third-party. If it is verified, then click the Yes button to proceed."

It specifies how to identify an unauthorized copy, but not what to do if you see it. I might add a "If it is verified, then click the Yes button to proceed,otherwise check the support forums for help..." or something similar.

p. 10 "3.4 Installing Scrivener on Linux"

Might be good to add a section stating that this all subject to change, since you are relying on volunteers, and outside of the company help. Just a thought. Steering them to the forums is probably the best thing.

p.10 "3.5 Staying Informed"

add info on how to get off the mailing list once you are on it.


Gah, gotta run, I had hoped to get more done... Hopefully later. Most of what I saw was pretty solid though.

[AmberV]

It specifies how to identify an unauthorized copy, but not what to do if you see it.

Thanks, that's a good point. I've added a sentence here for if this happens.

Might be good to add a section stating that this all subject to change, since you are relying on volunteers, and outside of the company help. Just a thought. Steering them to the forums is probably the best thing.

I've loosened up the terminology a bit to keep it vague. It already does point people to the forum. I've added a link to the wiki page too.

All other mentioned points have been addressed.

I had hoped to get more done... Hopefully later. Most of what I saw was pretty solid though.

Thanks, that's good to hear, and also thanks for the list.

[Lunarclipper]

I downloaded it, yesterday, but didn't have time to read it then. Now I can't find it. Where does it download too?