Page 1 of 1

After 15 years of people asking - Why is Bullet documentation still so very bad?

Posted: Sat Oct 10, 2020 8:03 pm
by Octavius_Ace
Apologies, for the deliberately provocative subject but I doubt I'm the only person to wonder this after years of usage.
  • Bullet is 15+ years old
  • A wiki was started, but is no longer available and seems not worthy of resurrection
  • The user manual is good but is really an overview
  • When people ask questions, they are directed to the examples
I often have to fall back on research papers, just to understand terms such as ERP and CFM.

There should be extensive documentation by now, whether provided by the author(s) or via the user base.
Looking at forum threads on this topic, it does look like there's been a lot of "foot dragging" on this.

Is the lack of documentation a deliberate policy?

What do others think ?

Re: After 15 years of people asking - Why is Bullet documentation still so very bad?

Posted: Wed Oct 14, 2020 4:54 pm
by pylover
This is everything but uncommon in the field of tooling for academic researches. One main problem is retention. Usually, people who use or contribute to these tools are in their academic research for a few years, and when their research finishes, they are pretty much done with this field. There isn't a great way of knowledge transfer, unlike in companies' engineering teams. Everyone basically has to ramp up on their own, and then rarely would they have the opportunity to pass their knowledge down to someone else. The lack of knowledge sharing is mainly due to 3 reasons:

1. Researchers' lives are usually fast-paced, and after already spending so much time ramping themselves up, they very likely do not have bandwidth left to document their ramp-up journey for later users to learn from.
2. Even if they do have the time to document, the potential rewards might seem not worth it as it's usually such a niche.
3. From maintainers' perspective, first they also have the retention issue (most people come and go quickly), and second, if taking ownership is systematically challenging or it's unclear how to do it, good documentation becomes something everybody wants but nobody does.

Additional points welcome.

Re: After 15 years of people asking - Why is Bullet documentation still so very bad?

Posted: Thu Oct 15, 2020 11:50 pm
by Octavius_Ace
Fair comment, I hadn't really considered the driving force being academic research and the implications therein. I'd assumed it was more a labour of love on the part of the primary author and others. I'm not saying it isn't both of course.

It's a pity that knowledge is being repeatedly gained and lost but appreciate the circumstances you describe.

Of course I shouldn't complain, as I've got a great piece of free software, irrespective of the state of the docs.
So perhaps I should just thank the authors and leave it at that.