doc: references and sw documentation