Details

    • Type: Task Task
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 0.9
    • Component/s: None
    • Labels:
      None

      Description

      The ASF CMS makes editing sites a whole lot easier using pub-sub and Markdown.

      We should move to it. We will be much happier. I'd even propose we move most of our wiki to it and let users comment instead of edit.

      1. mahout_site.tar.gz
        1.24 MB
        Isabel Drost-Fromm

        Issue Links

          Activity

          Grant Ingersoll created issue -
          Robin Anil made changes -
          Field Original Value New Value
          Status Open [ 1 ] Resolved [ 5 ]
          Assignee Robin Anil [ robinanil ]
          Resolution Not A Problem [ 8 ]
          Hide
          Isabel Drost-Fromm added a comment -

          Robin Anil You marked this issue as "not a problem" - could you please explain? As a result I assumed we might already be using the Apache CMS. However when hitting the "ASF CMS" bookmarklet on Mahout's front page, it doesn't show the usual Markdown based edit window, on Apache's title page it works as expected. Also we aren't listed as one of the projects using the CMS: https://cms.apache.org/

          For more information on the bookmarklet I'm using for my check: https://cms.apache.org/#bookmark

          Show
          Isabel Drost-Fromm added a comment - Robin Anil You marked this issue as "not a problem" - could you please explain? As a result I assumed we might already be using the Apache CMS. However when hitting the "ASF CMS" bookmarklet on Mahout's front page, it doesn't show the usual Markdown based edit window, on Apache's title page it works as expected. Also we aren't listed as one of the projects using the CMS: https://cms.apache.org/ For more information on the bookmarklet I'm using for my check: https://cms.apache.org/#bookmark
          Isabel Drost-Fromm made changes -
          Resolution Not A Problem [ 8 ]
          Status Resolved [ 5 ] Reopened [ 4 ]
          Hide
          Ted Dunning added a comment -

          Moving to CMS would be a very good step. I have been using CMS on Drill and it really is easier and works better.

          Show
          Ted Dunning added a comment - Moving to CMS would be a very good step. I have been using CMS on Drill and it really is easier and works better.
          Hide
          Isabel Drost-Fromm added a comment -

          Looks like the way to CMS is to:

          Show
          Isabel Drost-Fromm added a comment - Looks like the way to CMS is to: File an INFRA ticket to get a CMS: https://blogs.apache.org/infra/entry/the_asf_cms There's a howto for migrating from Confluence: https://svn.apache.org/repos/infra/websites/cms/conversion-utilities/cwiki/README.txt For those not familiar with Apache CMS: http://www.apache.org/dev/cmsref.html
          Hide
          Isabel Drost-Fromm added a comment -

          Apparently there is tooling for crawling confluence and migrating the confluence markup to markdown. As I had a few minutes time this weekend here's what I did:

          • Crawl our wiki
          • Convert the result to CMS markdown
          • Throw all pages into some form of navigation.

          What is missing:

          • Mahout css - currently the css is taken from the comdev page
          • Several links are broken, in particular the bread crumb navigation on top of each individual page
          • Some pages didn't make it through the automatic conversion
          • Images didn't make it through the automatic conversion
          • Several pages should be deleted due to quality reasons or as they describe deleted functionality

          The preliminary result (needing lots of cleanup, this is mostly based on an automatic conversion) is there:

          http://people.apache.org/~isabel/content/overview.html

          I'll attach the scripts, templates and content markdown in a minute. This is what you should read in order to generate above html files from that: http://www.apache.org/dev/cmsref.html#local-build

          Show
          Isabel Drost-Fromm added a comment - Apparently there is tooling for crawling confluence and migrating the confluence markup to markdown. As I had a few minutes time this weekend here's what I did: Crawl our wiki Convert the result to CMS markdown Throw all pages into some form of navigation. What is missing: Mahout css - currently the css is taken from the comdev page Several links are broken, in particular the bread crumb navigation on top of each individual page Some pages didn't make it through the automatic conversion Images didn't make it through the automatic conversion Several pages should be deleted due to quality reasons or as they describe deleted functionality The preliminary result (needing lots of cleanup, this is mostly based on an automatic conversion) is there: http://people.apache.org/~isabel/content/overview.html I'll attach the scripts, templates and content markdown in a minute. This is what you should read in order to generate above html files from that: http://www.apache.org/dev/cmsref.html#local-build
          Hide
          Isabel Drost-Fromm added a comment -

          First take on what a conversion of confluence to Apache CMS could look like (in particular look at the "content" directory for the markdown pages and the "templates" directory for where the black menu bar on top of the page comes from).

          Note: This version contains several flaws - the goal is mostly to share early, get feedback ... and have a place to put this stuff other than just my own hard-disk

          Show
          Isabel Drost-Fromm added a comment - First take on what a conversion of confluence to Apache CMS could look like (in particular look at the "content" directory for the markdown pages and the "templates" directory for where the black menu bar on top of the page comes from). Note: This version contains several flaws - the goal is mostly to share early, get feedback ... and have a place to put this stuff other than just my own hard-disk
          Isabel Drost-Fromm made changes -
          Attachment mahout_site.tar.gz [ 12607072 ]
          Hide
          Ted Dunning added a comment -

          Wow.

          Nice work.

          Show
          Ted Dunning added a comment - Wow. Nice work.
          Hide
          Isabel Drost-Fromm added a comment -

          One question: CMS would live in our subversion tree. Where would we want to have it - along-side trunk like the old "site" directory or underneath trunk? Is there any difference as to what makes it easier to release/tag documentation versions together with software releases?

          Show
          Isabel Drost-Fromm added a comment - One question: CMS would live in our subversion tree. Where would we want to have it - along-side trunk like the old "site" directory or underneath trunk? Is there any difference as to what makes it easier to release/tag documentation versions together with software releases?
          Hide
          Ted Dunning added a comment -

          I think beside trunk. Definitely not in it.

          My rationale is that the release cycles for each are completely disjoint.

          Show
          Ted Dunning added a comment - I think beside trunk. Definitely not in it. My rationale is that the release cycles for each are completely disjoint.
          Isabel Drost-Fromm made changes -
          Link This issue is depended upon by MAHOUT-1305 [ MAHOUT-1305 ]
          Hide
          Isabel Drost-Fromm added a comment -

          Makes sense.

          I added the content I had crawled including css adapted to what our site uses currently to site/mahout_cms, also created an INFRA-6959 ticket. We are to notify once we are happy with the cms based site to ship it to production.

          What needs to be done before having this site go live:

          • delete documentation that is irrelevant or mis-leading by now
          • fix pages with broken formatting to proper markdown
          • add pictures and graphs where they are missing
          • delete pages that we are going to provide through cms from confluence

          Most of the above should be possible with the Apache CMS in-browser editor - AFAIK no need to touch svn directly unless you want to, but those with more cms experience can provide the details here.

          Some pieces of history I found while digging through our site generation: Currently our site is based on svnpubsub (see also INFRA-4441 that Sean kindly pointed me at).

          There were some efforts being done back in mid 2012 to move to Apache CMS - see also mailing list discussion here: http://find.searchhub.org/document/d70ba51a99710ee2#d70ba51a99710ee2 and commit in revision number r1360593 - apparently nothing moved forward from there on so in revision r1491001 this summer the whole stub was deleted.

          Show
          Isabel Drost-Fromm added a comment - Makes sense. I added the content I had crawled including css adapted to what our site uses currently to site/mahout_cms, also created an INFRA-6959 ticket. We are to notify once we are happy with the cms based site to ship it to production. What needs to be done before having this site go live: delete documentation that is irrelevant or mis-leading by now fix pages with broken formatting to proper markdown add pictures and graphs where they are missing delete pages that we are going to provide through cms from confluence Most of the above should be possible with the Apache CMS in-browser editor - AFAIK no need to touch svn directly unless you want to, but those with more cms experience can provide the details here. Some pieces of history I found while digging through our site generation: Currently our site is based on svnpubsub (see also INFRA-4441 that Sean kindly pointed me at). There were some efforts being done back in mid 2012 to move to Apache CMS - see also mailing list discussion here: http://find.searchhub.org/document/d70ba51a99710ee2#d70ba51a99710ee2 and commit in revision number r1360593 - apparently nothing moved forward from there on so in revision r1491001 this summer the whole stub was deleted.
          Isabel Drost-Fromm made changes -
          Link This issue depends upon INFRA-6959 [ INFRA-6959 ]
          Hide
          Isabel Drost-Fromm added a comment -

          Mahout CMS on staging is up and running:

          http://mahout.staging.apache.org/

          Please use the Apache CMS bookmarklet and help with cleanup (meaning: Add images where missing, re-format, re-move deprecated stuff. Feel free to also delete pages that are no longer valid).

          Please check out http://www.apache.org/dev/cmsref.html#faq if you are not a committer and want to help with the cleanup.

          Show
          Isabel Drost-Fromm added a comment - Mahout CMS on staging is up and running: http://mahout.staging.apache.org/ Please use the Apache CMS bookmarklet and help with cleanup (meaning: Add images where missing, re-format, re-move deprecated stuff. Feel free to also delete pages that are no longer valid). Please check out http://www.apache.org/dev/cmsref.html#faq if you are not a committer and want to help with the cleanup.
          Hide
          Isabel Drost-Fromm added a comment - - edited

          Formatting changes to JIRA comment only for better readability. Click on each of the links, then hit the ASF CMS bookmarklet in your browser to start editing. Click "Submit" and in the following screen "Commit" - add a reasonable comment and commit.

          Links to pages that need to be touched in the general and developers tabs before publishing the cms mahout site. Please do install the cms bookmarklet in your browser and help with editing. No need to directly deal with Markdown in your editor in a file checked out from svn.

          Pages that need scrubbing:

          Pages that I believe can be deleted:

          Questionable content where I need your input:

          I'll quickly scan the pages in the remaining four tabs probably tomorrow.

          Show
          Isabel Drost-Fromm added a comment - - edited Formatting changes to JIRA comment only for better readability. Click on each of the links, then hit the ASF CMS bookmarklet in your browser to start editing. Click "Submit" and in the following screen "Commit" - add a reasonable comment and commit. Links to pages that need to be touched in the general and developers tabs before publishing the cms mahout site. Please do install the cms bookmarklet in your browser and help with editing. No need to directly deal with Markdown in your editor in a file checked out from svn. Pages that need scrubbing: http://mahout.staging.apache.org/general/powered-by-mahout.html ... the favicons do not work anymore * http://mahout.staging.apache.org/general/professional-support.html ... the links are broken http://mahout.staging.apache.org/general/reference-reading.html ... currently just a copy of a mailing list thread - needs sorting, categorisation etc http://mahout.staging.apache.org/general/faq.html ... headers look weird, also I'm sure we can think of more items for that list. http://mahout.staging.apache.org/developers/version-control.html ... needs working links and title http://mahout.staging.apache.org/developers/issue-tracker.html ... needs a title http://mahout.staging.apache.org/developers/gsoc.html ... needs information also for potential mentors - at least a link to comdev on how the Apache side of GSoC works (student selection etc) http://mahout.staging.apache.org/developers/how-to-update-the-website.html ... needs to link to cms and explain a few concepts behind it http://mahout.staging.apache.org/developers/patch-check-list.html ... needs better formatting http://mahout.staging.apache.org/developers/how-to-release.html ... formatting http://mahout.staging.apache.org/developers/thirdparty-dependencies.html ... minor formatting Pages that I believe can be deleted: Anything in the "stuff" tab. http://mahout.staging.apache.org/general/mahout-wiki.html ... link directly to wiki from template menu once wiki is cleaned http://mahout.staging.apache.org/general/glossary.html ... empty Questionable content where I need your input: http://mahout.staging.apache.org/general/mahout-benchmarks.html ... should move under recommender tab I'll quickly scan the pages in the remaining four tabs probably tomorrow.
          Hide
          Isabel Drost-Fromm added a comment - - edited

          Some more small pieces to fix:

          Scrubbing needed for:

          Delete:

          Overall I believe we need a better way of distinguishing docs for users, developers, JavaDocs and design docs.

          Show
          Isabel Drost-Fromm added a comment - - edited Some more small pieces to fix: Scrubbing needed for: http://mahout.staging.apache.org/users/basics/algorithms.html ... what I would like to see is for each a link to the JIRA issues containing the design discussion, a link to cmd line user documentation, a link to the java doc of the classes users should fist look at, a link to a page detailing the parallisation strategy http://mahout.staging.apache.org/users/basics/quickstart.html ... there's some weird formatting in here http://mahout.staging.apache.org/users/basics/mahout-collections.html ... needs a link to relevant javadocs http://mahout.staging.apache.org/users/basics/creating-vectors.html ... needs more text, linked pages need cleanup http://mahout.staging.apache.org/users/basics/collocations.html ... unclear what is meant for users, what is meant as background info, needs formatting cleanup as well http://mahout.staging.apache.org/users/basics/dimensional-reduction.html ... see comments above Delete: http://mahout.staging.apache.org/users/basics/mahoutintegration.html http://mahout.staging.apache.org/users/basics/matrix-and-vector-needs.html - only design discussion, maybe keep in wiki only? http://mahout.staging.apache.org/users/basics/gaussian-discriminative-analysis.html http://mahout.staging.apache.org/users/basics/independent-component-analysis.html Overall I believe we need a better way of distinguishing docs for users, developers, JavaDocs and design docs.
          Hide
          Isabel Drost-Fromm added a comment - - edited

          Tab classification:

          Scrubbing:

          Delete:

          Create:

          • We have a random forest implemenation - where's the docs (design, link to javadoc, issue etc.) for it?
          Show
          Isabel Drost-Fromm added a comment - - edited Tab classification: Scrubbing: http://mahout.staging.apache.org/users/classification/classifyingyourdata.html ... needs general remark on what classification is. Needs links to sgd. Needs links to javadocs in additional to cmd-line http://mahout.staging.apache.org/users/classification/bayesian-commandline.html ... weird formatting http://mahout.staging.apache.org/users/classification/wikipedia-bayes-example.html ... formatting http://mahout.staging.apache.org/users/classification/logistic-regression.html ... images missing, maybe link to one example about how to use the code from Java? Maybe create and link to package java doc for it? Delete: http://mahout.staging.apache.org/users/clustering/20newsgroups.html ... link to issue only from classifying your data if at all http://mahout.staging.apache.org/users/classification/class-discovery.html ... is this still relevant Anything under "Other designs" in Classification tab Create: We have a random forest implemenation - where's the docs (design, link to javadoc, issue etc.) for it?
          Show
          Isabel Drost-Fromm added a comment - Some more links for clustering: Scrubbing: http://mahout.staging.apache.org/users/clustering/clusteringyourdata.html ... formatting, kmeans++ missing http://mahout.staging.apache.org/users/clustering/cluster-dumper.html ... formatting http://mahout.staging.apache.org/users/clustering/k-means-clustering.html ... formatting, TOC http://mahout.staging.apache.org/users/clustering/k-means-commandline.html ... fold into above? http://mahout.staging.apache.org/users/clustering/canopy-clustering.html ... see above http://mahout.staging.apache.org/users/clustering/canopy-commandline.html ... see above same for all other clustering algorithms I don't find any docs on kmeans++ - are there any docs? http://mahout.staging.apache.org/users/clustering/clustering-of-synthetic-control-data.html ... formatting http://mahout.staging.apache.org/users/clustering/clustering-seinfeld-episodes.html ... move to books, tutorials, talks page
          Hide
          Isabel Drost-Fromm added a comment -

          Recommendations tab:

          Scrubbing:

          Show
          Isabel Drost-Fromm added a comment - Recommendations tab: Scrubbing: http://mahout.staging.apache.org/users/recommender/recommender-documentation.html ... images missing http://mahout.staging.apache.org/users/recommender/recommender-first-timer-faq.html ... if we have a recommendations FAQ here, we should also have one for clustering and one for classification - otherwise merge into global FAQ http://mahout.staging.apache.org/users/recommender/pearsoncorrelation.html ... move to java docs package docs completely, link to doc of packages containing plugable configurations (similarities etc.) http://mahout.staging.apache.org/users/emr/mahout-on-amazon-ec2.html ... formatting, title http://mahout.staging.apache.org/users/emr/mahout-on-elastic-mapreduce.html ... move in menu to clustering, title title http://mahout.staging.apache.org/users/emr/use-an-existing-hadoop-ami.html
          Hide
          Isabel Drost-Fromm added a comment -

          First blob of scrubbing (see comment 12/Nov/13 14:26 or tab developers) done except for the page deletions and the questionable content.

          Show
          Isabel Drost-Fromm added a comment - First blob of scrubbing (see comment 12/Nov/13 14:26 or tab developers) done except for the page deletions and the questionable content.
          Hide
          Isabel Drost-Fromm added a comment -

          Second scrubbing blob (12/Nov/13 14:26, see also tab "basics" on staging page) done except for page deletions.

          Show
          Isabel Drost-Fromm added a comment - Second scrubbing blob (12/Nov/13 14:26, see also tab "basics" on staging page) done except for page deletions.
          Hide
          Isabel Drost-Fromm added a comment -

          Note: Apparently the automatic wiki crawler forgot some pages - e.g. those linked under Documentation here: http://mahout.staging.apache.org/developers/developer-resources.html - file formats etc. need manual migration.

          Show
          Isabel Drost-Fromm added a comment - Note: Apparently the automatic wiki crawler forgot some pages - e.g. those linked under Documentation here: http://mahout.staging.apache.org/developers/developer-resources.html - file formats etc. need manual migration.
          Hide
          Isabel Drost-Fromm added a comment -

          Third blob of scrubbing done (see comment from 12/Nov/13 14:39 or tab classification on staging site) - deletions pending.

          Show
          Isabel Drost-Fromm added a comment - Third blob of scrubbing done (see comment from 12/Nov/13 14:39 or tab classification on staging site) - deletions pending.
          Isabel Drost-Fromm made changes -
          Assignee Robin Anil [ robinanil ] Isabel Drost-Fromm [ isabel ]
          Hide
          Isabel Drost-Fromm added a comment -

          All major formatting issues I found are fixed.

          There are still pages that need to be deleted - removing them from the navigation panel just now. There are two pages that were not migrated automatically. Before I go about pushing the site from staging to production it would be great to have another pair of eyes (or preferably a couple of other pairs of eyes) look over the current status.

          If you find stuff missing I think it's safe to add that after going to production. This is more about spotting stuff that is utterly wrong or outdated and misleading to users.

          Show
          Isabel Drost-Fromm added a comment - All major formatting issues I found are fixed. There are still pages that need to be deleted - removing them from the navigation panel just now. There are two pages that were not migrated automatically. Before I go about pushing the site from staging to production it would be great to have another pair of eyes (or preferably a couple of other pairs of eyes) look over the current status. If you find stuff missing I think it's safe to add that after going to production. This is more about spotting stuff that is utterly wrong or outdated and misleading to users.
          Hide
          Sebastian Schelter added a comment -

          Where can I see the current version of the wiki?

          Show
          Sebastian Schelter added a comment - Where can I see the current version of the wiki?
          Hide
          Isabel Drost-Fromm added a comment -

          That reads like a slightly confused question.

          The wiki itself is still in its old state - MAHOUT-1305 exists to re-work the wiki, which I believe should include killing content that has been moved to Apache CMS.

          http://mahout.staging.apache.org/ is where the current CMS based website is in staging. Once we are happy with that, I'll notify INFRA to disable our current svnpubsub based website and instead have mahout.apache.org point to the production version of our CMS based site.

          The code is checked into svn under site/mahout_cms

          In order to make edits I strongly advise you to install the Apache CMS bookmarklet in your browser which you can find here: https://cms.apache.org/ (scroll all the way to the bottom). Credentials are simply your Apache (svn and ssh) credentials. You can edit pages, submit changes and commit changes to the site from your browser.

          Show
          Isabel Drost-Fromm added a comment - That reads like a slightly confused question. The wiki itself is still in its old state - MAHOUT-1305 exists to re-work the wiki, which I believe should include killing content that has been moved to Apache CMS. http://mahout.staging.apache.org/ is where the current CMS based website is in staging. Once we are happy with that, I'll notify INFRA to disable our current svnpubsub based website and instead have mahout.apache.org point to the production version of our CMS based site. The code is checked into svn under site/mahout_cms In order to make edits I strongly advise you to install the Apache CMS bookmarklet in your browser which you can find here: https://cms.apache.org/ (scroll all the way to the bottom). Credentials are simply your Apache (svn and ssh) credentials. You can edit pages, submit changes and commit changes to the site from your browser.
          Hide
          Isabel Drost-Fromm added a comment -

          Unless I hear otherwise in the next three days I'll get the ball rolling to have this replace our current svnpubsub based page.

          Note: doing this before 0.9 would be nice, but we can update the cms based page at any time. Also it's build is independent of Mahout trunk as discussed earlier in this issue.

          Show
          Isabel Drost-Fromm added a comment - Unless I hear otherwise in the next three days I'll get the ball rolling to have this replace our current svnpubsub based page. Note: doing this before 0.9 would be nice, but we can update the cms based page at any time. Also it's build is independent of Mahout trunk as discussed earlier in this issue.
          Hide
          Isabel Drost-Fromm added a comment -

          Informed infra via INFRA-6959 to put the ASF CMS based version live instead of our current web site. After this is done, feel free to go ahead and delete obsolete pages from the wiki as part of MAHOUT-1305

          Show
          Isabel Drost-Fromm added a comment - Informed infra via INFRA-6959 to put the ASF CMS based version live instead of our current web site. After this is done, feel free to go ahead and delete obsolete pages from the wiki as part of MAHOUT-1305
          Hide
          Isabel Drost-Fromm added a comment -

          New Apache CMS based site is live. Thanks to Joe Schaefer for the support with getting this up and running.

          Show
          Isabel Drost-Fromm added a comment - New Apache CMS based site is live. Thanks to Joe Schaefer for the support with getting this up and running.
          Isabel Drost-Fromm made changes -
          Status Reopened [ 4 ] Resolved [ 5 ]
          Resolution Fixed [ 1 ]
          Suneel Marthi made changes -
          Status Resolved [ 5 ] Closed [ 6 ]
          Assignee Isabel Drost-Fromm [ isabel ] Suneel Marthi [ smarthi ]
          Transition Time In Source Status Execution Times Last Executer Last Execution Date
          Open Open Resolved Resolved
          4h 22m 1 Robin Anil 08/Jun/13 16:30
          Resolved Resolved Reopened Reopened
          118d 17h 13m 1 Isabel Drost-Fromm 05/Oct/13 09:43
          Reopened Reopened Resolved Resolved
          70d 7h 46m 1 Isabel Drost-Fromm 14/Dec/13 16:29
          Resolved Resolved Closed Closed
          50d 15h 27m 1 Suneel Marthi 03/Feb/14 07:57

            People

            • Assignee:
              Suneel Marthi
              Reporter:
              Grant Ingersoll
            • Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development