search

markstinson / google-styleguide

Automatically exported from code.google.com/p/google-styleguide
0 stars 0 forks source link

styleguide maintenance #36

Open GoogleCodeExporter opened 9 years ago

GoogleCodeExporter commented 9 years ago 
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 tibokr...@googlemail.com on 6 Jan 2015 at 5:59

GoogleCodeExporter commented 9 years ago 
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 tibokr...@googlemail.com on 7 Jan 2015 at 12:19