Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[IMP] setup/install: improves readability, corrects spelling errors, … #12051

Closed
wants to merge 1 commit into from

Conversation

Projects
None yet
3 participants
@tesserB
Copy link
Contributor

commented May 16, 2016

Description of the issue/feature this PR addresses:

This pull request aims to improve upon the structure, readability*, and completeness of the installation guide.

      -  It is overly explicit and assumes nothing about the users level of experience —or familiarity with tech, until after the Packaged Installer methods.

      -  The Demo and SaaS sections are more sales slanted, as there could be small business owners trying to make a go of Odoo on their own.

      -  Removes references to limitations, where they are unhelpful: "Odoo has no limitations" :: wink ::

      -  It's conversational and inviting, until after the Windows Packaged Installer methods, with the goal of signaling Small Business owners: "we're helpful and friendly.. Call us and we wont talk over your head.."

      -  Signals to Developers that Odoo might be an easier FOSS to work with: "it's obviously committed to documentation... And it's explicit?!?"

      -  It makes a point to avoid contractions and confusing idioms, where possible in order to aid translation/readability (i.e., you're to you are; je m'appelle to je me apelle)

      -  Strips some industry jargon/acronyms or approaches them more friendly ―potential customers, "I can do this"; developers, "I don't know x or y, but I could use this and contribute z..."
  • See below...

Is Your Business Writing Too Smart for Its Own Good?
http://www.printwand.com/blog/is-your-business-writing-too-smart-for-its-own-good

How to Write for an Eighth-Grade Reading Level
http://www.proedit.com/how-to-write-for-an-eighth-grade-reading-level/

Current behavior before PR:
Flesch-Kincaid Grade Level, SMOG, Coleman Liau Avg: 12th Grade

Desired behavior after PR is merged:
It's not ready to be merged. Just looking for guidance:

Flesch Kincaid Grade Level: 9th Grade
Flesch Kincaid Reading Ease: +11 points

I confirm I have signed the CLA and read the PR guidelines at www.odoo.com/submit-pr
Cody Kitterman

[IMP] setup/install: improves readability, corrects spelling errors, …
…improves explicitness, adds references, separates concerns within installation doc...
@Yenthe666

This comment has been minimized.

Copy link
Collaborator

commented May 16, 2016

@mart-e check this out, that is some enjoyable content to read. What do you think about this?
+1 @tesserB

@tesserB

This comment has been minimized.

Copy link
Contributor Author

commented May 16, 2016

@mart-e I don't care for Spiderman either: I don't read comics and I gave my TV away years ago... It's in there because it's about to mention a superficial limitation/drawback.... I feared people might not like hearing about those, given it's in the earliest of stages. I just thought it was a non-technical way of conveying that 'freedom comes with a rope to hang oneself with'/"le corde pour se pendre", which people understand, and I couldn't think of anything else... That being said, if anyone can think of something...

In closing, I know my additions still need heavy editing, but is it something you guys would be willing to work with? I would like to know before I put anymore time into it...

@Yenthe666 Documentation that's enjoyable to read? Whaaat? ;-) Thank you, sir.

@tesserB

This comment has been minimized.

Copy link
Contributor Author

commented May 21, 2016

@fhe-odoo Would you mind checking these out for me, man, and letting me know if this is something Odoo would be willing to work with? I know it needs further editing, but I've asked others for input on the structural changes, and I haven't heard a peep. I understand some of that—"'everyone' already knows this stuff"—but I would like to finish these up, and move on to more significant improvements.

@mart-e mart-e self-assigned this Jun 2, 2016

@tesserB tesserB closed this Jul 25, 2016

@tesserB tesserB deleted the tesserB:master_setup_doc branch Jul 25, 2016

@Yenthe666

This comment has been minimized.

Copy link
Collaborator

commented Jul 26, 2016

🌵 any reason why you've deleted it @tesserB?

@tesserB

This comment has been minimized.

Copy link
Contributor Author

commented Jul 27, 2016

@Yenthe666 I was being lazy in regards to my github fork... Anyway, man, sorry... I'll get it back up...

@Yenthe666

This comment has been minimized.

Copy link
Collaborator

commented Jul 27, 2016

@tesserB no worries, it is still there and I think @mart-e can still merge this despite that delete.
@mart-e can we pick this up again too please?

@tesserB

This comment has been minimized.

Copy link
Contributor Author

commented Jul 27, 2016

@yenthe - I'm working on it now and expect I'll have an improved version
this afternoon: better formatting, smaller/easier to read commits. Marty
and I had hammered out some formatting stuff, too, with respect to the
cmdline doc. If you'll email me directly, ckitterm@gmail.com, I'll fill you
in... I had some other business I wanted to talk to you about anyway...

On Wed, Jul 27, 2016 at 9:12 AM, Yenthe notifications@github.com wrote:

@tesserB https://github.com/tesserB no worries, it is still there and I
think @mart-e https://github.com/mart-e can still merge this despite
that delete.
@mart-e https://github.com/mart-e can we pick this up again too please?


You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#12051 (comment), or mute
the thread
https://github.com/notifications/unsubscribe-auth/ANfOx8k2-lQnWx0MkyaSOUFdT6k5kUevks5qZ1lDgaJpZM4IfJYL
.

@Yenthe666

This comment has been minimized.

Copy link
Collaborator

commented Jul 27, 2016

@tesserB I've emailed you. You can remove your e-mailadres here now if you don't want to many people having it. 😄

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.