Minutes

Notes from April 7^th Meeting of LFN Community Documentation Evangelists

• Define best practices for documentation for all of lfn
• Do we need a documentation best practices page on the lfn Wiki?
• Should we create templates?
• Documentation badging or badges 4 contributors
• Doc maps, defining as a best practice
• Semantic Commit documents

Introduction by Scot Steele – Provide consistency across all the LFN projects.  Not rigid standards, but more guidelines and frame work.  We will be also looking at tools, but need to determine what is included in the framework.

Cedric Ollivier : Best practices across many LFN projects.  Mostly the same processes, but the tools are different across the projects.  The problem is more about getting projects to follow the existing guidelines.  Possibly the processes need to be changed a bit, but do not need to be rewritten from scratch.   Need to make sure we have captured the documentation process to make sure that it is following the existing guidelines.

• Harmonize the tooling
• Identify a common set of documents that would apply across all the projects.  Not all projects will need to do all the docs – code projects will be different from requirements projects, for example.
• Guidelines for docs, some will be required, some will be optional.  Core set of required docs for all projects.

Discussion of where to put the docs.  Not everything will be put in a wiki or a Readthedocs.  We also need to have set of guidance of what docs go where. Two audiences, the developers working on their existing projects, and the new projects just starting.  Let’s start with new projects so they get it right from the beginning.  The old projects, hopefully will see the light and convert.

Wikis are for working docs and minutes of meetings, should not be used for “official” release documentation.  Wikis are for project management docs.  Lifecycle docs are lacking in general.  If your project does not have the minimum required docs, it should not be released.  There is little coordination across projects today.

For a new project, some guidelines with a list of docs that are needed to help make the project successful.  We are not starting from scratch, but take from the existing best practices and build on them.

We have reached agreement on:

• We need to do a better job of managing the wikis – keeping them up to date, not get stale, many of them are a mess.  Wikis ARE NOT A GOOD METHOD OF DOCUMENTATION.
• We need to have a set of guidelines (map) across all the projects – set of best practices
• Need to continue to harmonizing on the tooling

Action items

• Scot Steele to schedule next call for 4/21
•