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.

Sign up for GitHub

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

Jump to bottom

styleguide maintenance #36

Open
GoogleCodeExporter opened this issue Apr 28, 2015 · 1 comment
Open

styleguide maintenance #36

GoogleCodeExporter opened this issue Apr 28, 2015 · 1 comment
Labels
auto-migrated Priority-Medium Type-Defect

Comments

@GoogleCodeExporter
Copy link 

Hi,

I see some problem with the maintenance of the styleguide as a project:

- The project contains no README, LICENSE, CONTRIBUTING or CHANGELOG file (the 
project homepage contains that information instead, of course, but that's not 
how to do open-source, forks should have this information)
- The project homepage does not link to this issue tracker
- The homepage does not mention a maintainer, it is not clear at all who will 
respond to issues, and who may decide about style changes.
- some HTML sources have xml file ending
- Eclipse/IntelliJ settings files in the repo are not linked from the homepage 
or any of the guides
- The styleguides follow different conventions (xsl vs. css for styling, 
different versioning schemes (last changed vs revision number))
- cpplint.py would benefit from being hosted independently on github or similar 
(I forked to my personal github repo at https://github.com/tkruse/cpplint)
- Maintenance of the guides would be more convenient if the HTML/XML sources 
were written in a markdown dialect or reStructured text instead of xml. 
Possibly presenting via readthedocs would yield beautiful yet cheap results
- The Common LISP Guide contains General guidelines regarding any project, not 
just LISP
- code examples have no syntax highlighting
- all language specific guides would do well to include further configuration 
for the various existing static checker tools, such as checkstyle for Java or 
pep8 for python etc. This would work better if there were more of a folder 
structure.

In other words, the styleguide itself as an open-source project does not set a 
great example for how google should present open-source projects, IMO.

Compare the effort that goes into this project with the effort that went into 
material design guide: 
http://www.google.com/design/spec/material-design/introduction.html

Making the styleguide itself a model open-source project would easily be 
feasible as Summer of Code project or similar.

Original issue reported on code.google.com by [email protected] on 6 Jan 2015 at 5:59
@GoogleCodeExporter
Copy link
Author 

In case translating html / xml to some other format seems too painful to 
anyone, it is not too difficult using pandoc. To demonstrate this, I forked the 
styleguide here:
https://github.com/tkruse/styleguide

and added a Makefile that invokes pandoc on all files converting them 
eventually to Asciidoc. Those rendered okay on github, as you can see by 
opening any *.asciidoc file. Looking at the Makefile you can see it's not 100% 
straightforward, but really not bad at all.

Pandoc could also render to Markdown, rst, textile, wiki, etc.
Anything would be better than the current mix of xml, html, xsl and javascript. 


(Also I noticed the file xmlstyle.html lacks opening <html><head><script> tags, 
and simlar closing </body> and </html> tags. More irony given this is an xml 
style guide). And it seems to have some encoding issues as well.

Original comment by [email protected] on 7 Jan 2015 at 12:19

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
auto-migrated Priority-Medium Type-Defect
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@GoogleCodeExporter