# Reworking package documentation **URL:** \ **Category:** Talk about Documentation\ **Created:** [November 29, 2024, 12:25pm UTC](https://forum.openwrt.org/t/reworking-package-documentation/216886 "2024-11-29T12:25:50Z")\ **Posts on this page:** 5\ **Page:** 1
**Author:** ![totkeks](https://forum.openwrt.org/user_avatar/forum.openwrt.org/totkeks/32/87704_2.png) [@totkeks](https://forum.openwrt.org/u/totkeks)\ **Post date:** [November 29, 2024, 12:25pm UTC](https://forum.openwrt.org/t/reworking-package-documentation/216886/1 "2024-11-29T12:25:51Z")
Based on this suggestion [Community question: What do you want to see in OpenWrt? - #25 by antonk](https://forum.openwrt.org/t/community-question-what-do-you-want-to-see-in-openwrt/216706/25), I'd like to bring forward an idea I had in order to improve the documentation in the wiki, so it is up to date and available for different supported OpenWrt versions. Problem: - Information in the wiki is not up to date, e.g. does not reflect the current state of the package and its available configuration options - Information does not show the OpenWrt version it applies to and multiple versions of the same information are not supported Solution: - Place documentation for the packages with the packages in the git repository - this ensures it is updated, when the package is updated as part of the PR review process - Generate documentation website automatically from documentation files for different branches (main, 24.X, 25.Y, ...) There is no technology set for the implementation of the solution. I'd rather open the thread to discussion on the general idea first and once that is settled and hopefully accepted, another brainstorming can go on for the technological implementation. What do the experienced OpenWrt members, developers and users, think about this? ---
**Author:** ![bluewavenet](https://forum.openwrt.org/user_avatar/forum.openwrt.org/bluewavenet/32/4330_2.png) [@bluewavenet](https://forum.openwrt.org/u/bluewavenet)\ **Post date:** [November 29, 2024, 1:23pm UTC](https://forum.openwrt.org/t/reworking-package-documentation/216886/2 "2024-11-29T13:23:02Z")
Documentation is hard! > [@totkeks](#): > > Solution: > > - Place documentation for the packages with the packages in the git repository - this ensures it is updated, when the package is updated as part of the PR review process > - Generate documentation website automatically from documentation files for different branches (main, 24.X, 25.Y, ...) Yes. I have done this with the openNDS package. It is not integrated in any way with OpenWrt, as no standard integration route is available, but is an example of what can be done. > **[openNDS/docs at master ยท openNDS/openNDS](https://github.com/openNDS/openNDS/tree/master/docs)** > > openNDS (open Network Demarcation Service) is a high performance, small footprint, Captive Portal. It provides a border control gateway between a public local area network and the Internet. - open... Github automagically pokes readthedocs to generate a new set of docs whenever a PR is merged.... [https://opennds.readthedocs.io/en/stable/](https://opennds.readthedocs.io/en/stable/) ---
**Author:** ![antonk](https://forum.openwrt.org/user_avatar/forum.openwrt.org/antonk/32/93698_2.png) [@antonk](https://forum.openwrt.org/u/antonk)\ **Post date:** [November 29, 2024, 2:14pm UTC](https://forum.openwrt.org/t/reworking-package-documentation/216886/3 "2024-11-29T14:14:33Z")
These are good ideas. That said, my suggestion to improve documentation goes beyond solving the 2 specific problems you identified. There are a lot of issues with the documentation in its current state. The 3 most significant issues (at least for me) are: 1. Documentation is spread across quite a few resources, especially documentation for developers. 2. Much of the documentation is outdated, without being clearly marked as such, which causes people to waste their time trying out things which are known not to work. 3. While probably it's hard to find someone who would want to proactively maintain the documentation, it could be maintained by the community, however there appears to be no established process for that. So when someone finds an issue in the documentation, they don't know what to do in order to get it fixed. So it doesn't get fixed. I understand that this is a volunteer project and everybody does what they like, and no one is responsible for making the project easy to use and contribute to. I'm just pointing out the issues that I'm seeing, in case someone does want to put their time into improving the situation. ---
**Author:** ![totkeks](https://forum.openwrt.org/user_avatar/forum.openwrt.org/totkeks/32/87704_2.png) [@totkeks](https://forum.openwrt.org/u/totkeks)\ **Post date:** [November 29, 2024, 2:40pm UTC](https://forum.openwrt.org/t/reworking-package-documentation/216886/4 "2024-11-29T14:40:57Z")
Thanks for your input, Anton! > [@antonk](#): > > While probably it's hard to find someone who would want to proactively maintain the documentation, it could be maintained by the community, however there appears to be no established process for that. So when someone finds an issue in the documentation, they don't know what to do in order to get it fixed. So it doesn't get fixed. Fully agree, I like if processes are in place and they are easy to access. For example, I know some projects where each documentation page has a "report an issue on GitHub" link at the bottom or somewhere prominent. Also using GitHub there are various ways to provide issue and PR templates and automated checks using workflows or bots. Also, GitHub provides a lot of their features for free on public repos and even more features to accredited OSS projects, which OpenWRT could clearly be. Just thinking beyond the docs, there is automated security vulnerability scanning, which was mentioned in the other thread about the future as well. But I don't know how interested the project is in using more of GitHub's features, since their primary method of communication, as far as I understood, is the self-hosted git and the mailing list(s). ---
**Author:** ![efahl](https://forum.openwrt.org/user_avatar/forum.openwrt.org/efahl/32/50404_2.png) [@efahl](https://forum.openwrt.org/u/efahl)\ **Post date:** [November 29, 2024, 7:05pm UTC](https://forum.openwrt.org/t/reworking-package-documentation/216886/5 "2024-11-29T19:05:42Z")
> [@antonk](#): > > So these are 5 separate locations to look for information, This one prompts me to suggest: 1. The built-in wiki search is very poor, which makes discovery of what you're looking for far too much work. This cascades into lack of maintenance, because if you can't even find an outdated page to begin with, there's no chance you could update it. Maybe simply partitioning it to "wiki-only" and "toh-only" would help a lot, as most often my results are overwhelmed by hundreds of ToH topics that I don't care about.