[
https://issues.apache.org/jira/browse/MAHOUT-1648?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14368061#comment-14368061
]
Andrew Palumbo edited comment on MAHOUT-1648 at 3/19/15 8:01 PM:
-----------------------------------------------------------------
Proposal for a loose documentation standard:
I am thinking that it would be good to have a loose convention to keep a
somewhat uniform look and feel to the documentation. I'm specifically looking
at the Legacy pages right now, I know we don't want to spend too much time on
this and may not be keeping all of them. But we do have a couple of algorithms
that will be going into spark so It would be good to come up with a (loose)
standard.
This would include:
Formatting:
# Use MathJax tex formatting for any math.
# All code blocks rendered as code
# References throughout.
# Single # for Page Titles
# Double # (##) for Section Headers
Layout (for algorithms, in order):
# Have a brief overview of the Algorithm at the top.
# A more detailed description of the algorithm including any pseudocode (if
applicable - if it is a novel algorithm or is a variation n a standard
algorithm)
# CLI Example if applicable.
# CLI Options if applicable.
# A code integration example if applicable and.
# Links to Examples and references at the bottom.
Obviously these aren't stoppers but I think following some small guidelines
would go a long way in making the documentation easier to follow.
IMO the most important thing is to get all pages updated to use MathJax.
Most pages are close to this now. I looked through and tried to take what was
used most often.
Any feedback is helpful.
was (Author: andrew_palumbo):
Proposal for a loose documentation standard:
I am thinking that it would be good to have a loose convention to keep a
somewhat uniform look and feel to the documentation. I'm specifically looking
at the Legacy pages right now, I know we don't want to spend too much time on
this and may not be keeping all of them. But we do have a couple of algorithms
that will be going into spark so It would be good to come up with a (loose)
standard.
This would include (for algorithms):
Formatting:
# Use MathJax tex formatting for any math.
# All code blocks rendered as code
# References throughout.
# Single # for Page Titles
# Double # (##) for Section Headers
Layout (for algorithms, in order):
# Have a brief overview of the Algorithm at the top.
# A more detailed description of the algorithm including any pseudocode (if
applicable - if it is a novel algorithm or is a variation n a standard
algorithm)
# CLI Usage if applicable.
# CLI Options if applicable.
# A code integration example if applicable and.
# Links to Examples and references at the bottom.
Obviously these aren't stoppers but I think following some small guidelines
would go a long way in making the documentation easier to follow.
IMO the most important thing is to get all pages updated to use MathJax.
Most pages are close to this now. I looked through and tried to take what was
used most often.
Any feedback is helpful.
> Update Mahout's CMS for 0.10.0
> ------------------------------
>
> Key: MAHOUT-1648
> URL: https://issues.apache.org/jira/browse/MAHOUT-1648
> Project: Mahout
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 0.9
> Reporter: Pat Ferrel
> Assignee: Andrew Palumbo
> Priority: Blocker
> Fix For: 0.10.0
>
>
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
