Possible additional info/templates etc.

[dbaarda]

Not sure if this is the best place/way to add a suggestion, but I couldn't find any other obvious way. Feel free to point me at a discussion list or email address if this is the wrong place.

A long time ago I had an attempt at putting together advice and templates on documenting open source projects which is here;

http://minkirri.apana.org.au/~abo/projects/prjdocs/ProjectDocs.txt
http://minkirri.apana.org.au/~abo/projects/prjdocs/templates/

The templates are all in reStructuredText, not markdown, which has the advantage of being more readable as plaintext but would be easy to convert.

There are some bits I didn't quite polish up that well, and I think there are some bits missing (like "Design Decisions" documenting differences/similarities to other projects, libraries considered, design approaches taken/rejected etc).

I don't know if you'd find any of this useful, but feel free to copy/ignore/whatever.

[pengwynn]

Excellent ideas there!

This project is as much about spreading the wisdom in these documents as it is providing the means to check the project, so I'm open to experimentation. For the first pass, I wanted to just check for common problems, like most lint utilities do, but eventually I'd like to fix the project by adding the suggested assets.

I don't think the initial CLI flags will scale for this number of templates. I'm thinking about scaling those back to just 'severity' levels and you can see [INFO], [WARNING], and [CRITICAL] suggestions as you so desire. Each template would be classified as such.

I'm also not sure how far I want to push bash before switching to something higher level. Thoughts?

[dbaarda]

Ugh... sorry was about to leave a comment, decided it was a stupid comment, and wanted to cancel posting it, not close this issue.

I have a Python framework for doing lint&fix type stuff that I wrote at work. I have have permission to open-source it, but it needs me to tidy it up a bit first, and realistically I dunno when I'm going to find time to do that. If you really want it and keep bugging me I'm more likely to find the time :-)

[dbaarda]

For the record, I've updated my http://minkirri.apana.org.au/~abo/projects/prjdocs/ProjectDocs.txt to include suggested contents for DEVELOPMENT and DESIGN documents, and updated the (README|INSTALL).(CSV|SVN) documents to say they are commonly seen older documents that are not recommended any more.