Obnam → blog → 2025 → Obnam 3: documentation; open up project
  1. Goal
  2. Plan
  3. Notes
  4. Summary
  5. Comments?

Goal

I want to open up the project for contributions from others. I think the functionality is now there: there's a bunch of things I'd like to still do, but it might be better to not polish too much. Instead, I'll want to make it easy to start hacking on the code. My goal today is to review all documentation and update it as needed. I'll also want to make sure what is useful to publish is published on a web site, not just in the Git repository.

Plan

  • Make a list of all documentation to review.
  • Review it, making notes of what needs updating.
  • Update it.
  • Publish what's usesful to publish on doc.obnam.org

Notes

List of documentation

  • Reviewing all the files in Git, I make the following list of documentation to review:
    • README.md - should document how to build code and docs, run tests, provide map to what's where
    • doc directory - review, update, publish
    • obnam.md - review, update, publish
    • roadmap.yaml - drop, I think
    • src - review and update documentation comments

Review documentation

I'll make small, local changes as I review.

  • README.md
    • made a bunch of improvements
    • really needs a "getting started" example or separate doc
    • needs to say how patches are to be provided
    • needs to point at some place where discussions are held: fedi?
  • doc directory
    • main Makefile does not format docs (fixed that)
    • arch.md seems OK; some typos, but I'm not going to worry about those; written before development started, so very tentative and could benefit from updating to make clear what is actually implemented
    • glossary.md - added
  • obnam.md
    • should possibly be split into "high level" and "detailed" acceptance criteria, for "users" and "developers" of Obnam
    • could perhaps be updated to be less tentative and less about the exploration phase
    • made some updates to clarify what the document is about and how to contribute to it
  • roadmap.yaml
    • removed; the source code repository feels like the wrong place for this
  • src files
    • reviewed, no notes

Update

  • Wrote a getting started doc. It's not great, but Obnam is not yet great to use.

Publish

  • Ran out of time for this. Next time. I don't think this needs to be a blocker for opening up the project.

Summary

Made a bunch of improvements to documentation in preparation of opening up the project for contributions. I think I can do that now. There's always more to do.

The Obnam project is now open for contributions by other people.

Comments?

If you have feedback on this development session, please use the following fediverse thread: https://toot.liw.fi/@liw/115280877334935648.