Apache Mahout README.md review

[MaineC]

Hi,

first of all, thanks for this initiative! I think explicitly getting feedback on project documentation is an awesome idea.

As for the actual help request: It would be lovely to get feedback for the following readme:

https://github.com/apache/mahout/blob/master/README.md

Please note that while I'm part of the group of committers listed for this project, me posting this issue here is my personal initiative. So when posting feedback it might be worthwhile to let people know that I'm the one to blame for seeking input.

As an additional note, people on our project are right now working to improve the documentation and website. So in case of time left, feedback on the progress made there, as well as on how easy it is to find that progress as a new motivated contributor would be highly appreciated.

Thanks again, Isabel

[LappleApple]

Thanks, @MaineC! Will get to this ASAP.

[shaloo]

@LappleApple : Kudos for this initiative. I don't fully understand the steps to chip in here - hence using comment route for now. Not sure if it is ok to modify this readme on GitHub?

For Mahout Readme:

1. It would be nice to include the following from the project web page about Mahout high level features.

   Apache Mahout software provides three major features:

   • A simple and extensible programming environment and framework for building scalable algorithms
   • A wide variety of premade algorithms for Scala + Apache Spark, H2O, Apache Flink
   • Samsara, a vector math experimentation environment with R-like syntax which works at scale

2. Use 'Spark' in with capital 'S'. For example: Under the 'Configuration' sub-heading it says "When building mahout for a spark backend, we need four System Environment variables set:"

That is all for now. Thanks.

[LappleApple]

@shaloo This is great! Usually I just go right into the README file after reading the contributing guidelines, make changes, and make a PR. But it's good that you're being a little cautious here. Will wait for @MaineC to respond, but meantime thank you and it's exciting to have you here.

[MaineC]

@shaloo The actions @LappleApple describe are pretty much what I would do as a new contributor to Apache Mahout as well.

I'm not a new person working on Mahout, so consider me blind for newcomer issues. Please point out any documentation either in the README itself or on your way to a successful contribution that slows you down.

At the bottom of the README there's a link to this: https://mahout.apache.org/developers/how-to-contribute.html

Which at the very bottom has a link to this: https://mahout.apache.org/developers/how-to-contribute.html

Feel free to suggest re-organising these if you think that would make sense.

If you feel uncomfortable going from "I've read this stuff" to "I'm making changes" right away, you're very much welcome to join our development mailing list: https://mahout.apache.org/general/mailing-lists,-irc-and-archives.html (and yes, at least for Apache Mahout changing the docs is considered development work, for more details on that concept see here: https://community.apache.org/apache-way/apache-project-maturity-model.html )

For background on why I direct you to such an arcane thing as a mailing list: https://blogs.apache.org/foundation/entry/success-at-apache-asynchronous-decision ;)

[MaineC]

One more thing: If any of my bubbling above is at all helpful but missing from the docs, point that out as well.

[shaloo]

@LappleApple: @MaineC: Thanks for these inputs, I did take a look at all these links. Haven't yet absorbed all the data in archives but tried to search Mahout Jira to figure out the acceptable way to update README (via prior updates). Not much luck there yet. What I wanted to know is: For a minor change in README such as say 'spark' to 'Spark', do I need to do a full fork->change->run-all-mahout tests->PR->and there on or is there a different path for doc updates?

[MaineC]

It's probably easiest to point that out on the Dev mailing list.

As an aside, I'm surprised this is really the only issue there is...

Am 10.07.2017 4:37 nachm. schrieb "Shaloo Shalini" <notifications@github.com

:

@LappleApple https://github.com/lappleapple: @MaineC https://github.com/mainec: Thanks for these inputs, I did take a look at all these links. Haven't yet absorbed all the data in archives but tried to search Mahout Jira to figure out the acceptable way to update README (via prior updates). Not much luck there yet. What I wanted to know is: For a minor change in README such as say 'spark' to 'Spark', do I need to do a full fork->change->run-all-mahout tests->PR->and there on or is there a different path for doc updates?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/LappleApple/feedmereadmes/issues/12#issuecomment-314125434, or mute the thread https://github.com/notifications/unsubscribe-auth/AAEVKQRirs-ZddLtymgf9xotz6GlALoSks5sMjcPgaJpZM4OQlrJ .

[shaloo]

Yes, there are others as well. I'll put all those together in one shot and submit to dev mailing list. Thanks.

[LappleApple]

@shaloo Thank you again for being here. :)

[shaloo]

@MaineC , @LappleApple : Thank you for your patience. Here is what I'd like to suggest for Mahout README. As a matter of fact, some of the well established OSS components README files could be rewritten using Structured README concept as an example. Please visit https://github.com/shaloo/structuredreadme.

I plan to send this to dev mailing list as well.

My next steps are to update Mahout README as a Structured README (modular manner) and see if that is helpful. feedmereadme inspired me to this approach. Just like feedmereadme provides help with reviewing README, Structured README could encourage technical writers, product management, journalists, CXOs and others who need to decide about using a OSS component vs another to also chip in contributing to OSS, besides the developers.

[MaineC]

Feel free to post as a pull request to the project as well.

[fokusferit]

@shaloo sorry that I just jump into the discussion as I checked your structuredreadme project it is a nice idea. Just out of curiosity why not doing a PR into here or Zalando Readme Template I think bundling the efforts would be much better but these are just my thoughts there is no need 😄 I wanted to highlight that you idea and motivation is similiar to this one here and contributing together on the ideas would result in much more benefit

[shaloo]

@fokusferit - Thats a great idea! I'd like to add a few more things to 'Structured Readme'. I'd like to redo Mahout README as a 'Structured README' and then share it with dev/mailing list. I'm inspired by @LappleApple too. Feedmereadme uses a pull model where README creators push reviewable content where community offers inputs. I'd like to support this via a push model as well - say via structured README whereby anyone in the community can create a structured README if they come across one which belongs to a useful OSS but lacks in terms of 'attracting easy adoption'. I believe users of OSS have great feedback and this could be one way to connect users with software creators. Its just that users (devs) don't feel like spending time with READMEs. That is where tech writers / product managers, who use software but don't code necessarily, could provide help for READMEs.

I'll open a PR for combining/refactoring structured README into [Zalando Readme Template](Zalando Readme Template) the moment I get a few idle cycles . Thanks again!

[shaloo]

@LappleApple: Can u pls help? I see 3/7 tasks completed - what did I miss? I'm using GitHub web interface and tried to use pull_request template.

[MaineC]

@shaloo Did you have time to work on the MAHOUT readme and share your findings already?

No need to rewrite and polish everything before you come back to the mailing list and propose your idea. Try to follow Yoniks law of unfinished patches: "A half-baked patch in Jira, with no documentation, no tests and no backwards compatibility is better than no patch at all." and post your ideas early on.

[shaloo]

Hi @MaineC, thanks for the tip, thats a good idea. Will do so the moment I get a small breather from current schedule, its on my to do list and I have all the good intentions to tackle it over the weekend :-)

[LappleApple]

Just saying hello and +1 on your continued collaboration. Read out if you need anything.