Outdated/confusing information and documentation

Started by unicorn, June 27, 2020, 05:41:40 pm

Previous topic - Next topic

unicorn

Hey,

I have noticed many times now that documentation is spread in many places and much of it is outdated. The wiki page for the LIME2 for example has not been updated since late 2019, or when wanting to download a linux image there are now two places: http://images.olimex.com and the (now deprecated as far as I understand) FTP server at ftp://staging.olimex.com with different images available in each place. Both of them are mentioned or linked in various places.
The user manual for the LIME2 was last revised in 2017, there are many links spread across many pages pointing to seemingly abandoned GitHub repos without any guidance.

I understand you have a lot of products to maintain, but I feel like the lack of clear and up-to-date documentation is a big issue for anyone wanting to get on board with your products. I highly recommend starting an internal initiative for unifying your documentation and just getting rid of massively outdated things for the purpose of reducing confusion. Right now it looks like quite a clusterfuck (excuse the language) to me and I don't feel like there is any place that I can rely on for up-to-date links and documentation for the hardware I bought, so I end up forced to dig through wikis and forums and your blog, often with little success and much frustration.

Is this an issue that you see aswell? If yes, then do you have any plans for changes in this direction? I'd be happy to hear from you and discuss. :)

JohnS

I find the hardware revision data via the published links, which IIRC are github.

John

unicorn

Quote from: JohnS on June 27, 2020, 07:00:24 pmI find the hardware revision data via the published links, which IIRC are github.

I was not saying that the info does not exist, I was saying it is all over the place and mixed with outdated info. :)
Just from the product page of the A20 LIME2 you would not be able to find the https://images.olimex.com site. It leads you to various outdated documents and pages with confusing and conflicting information. I know that the correct, up to date info exists somewhere in most cases, it's just a matter of making it visible and available in the right places, instead of forcing people to ask and search for hours.

Especially as a less experienced person, you will struggle a lot or be completely unable to find the right information without asking.