styleguide maintenance

[GoogleCodeExporter]

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

[vapier]

there's a lot to unpack here. in the future, please use sep issues for sep requests. it's a pita to track multiple things in one report, and basically guarantees it stays open forever, and it's hard to have discussions. as such, i'll close this out, and if you feel specific things still need addressing, please open a new report for each one.

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)

this is largely fixed with the GH migration, or at least as much as we plan on doing.

The project homepage does not link to this issue tracker

it does now

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.

the homepage makes this clear: there is no single maintainer, and responses are not guaranteed

some HTML sources have xml file ending

prob fixed as part of our ongoing format migrations. if you still see something, file a new issue for it please.

Eclipse/IntelliJ settings files in the repo are not linked from the homepage or any of the guides

this is probably still true

The styleguides follow different conventions (xsl vs. css for styling, different versioning schemes (last changed vs revision number))

yeah, this is an artifact of diff teams being responsible for each language, and the guides being written/migrated at diff points in Google's history. some internal work happens from time to time to change formats (e.g. shell switching from xml to md), but it's not something we're tracking externally.

cpplint.py would benefit from being hosted independently on github or similar

we prob should delete it from this repo entirely and declare bankruptcy and point people to https://github.com/cpplint. but there's other issues open about this topic.

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

maybe, but see above wrt file formats.

The Common LISP Guide contains General guidelines regarding any project, not just LISP

OK

code examples have no syntax highlighting

depends on the language I think

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.

probably. Google internally has these same issues.