#19 Lack of good documentation

Open
opened 6 years ago by RISCI_ATOM · 11 comments

The libreCMC has had a lack of documentation for most of the project's life due to lack of time and upstream docs being non-free (CC-BY-NC-SA) or tainted with documentation from the same / similar source.

libreCMC documentation needs to be cleanly written and can't be tainted with non-free documentation (all docs should be licensed CC-BY-SA). The reason this is a concern is because vendors who sell devices with libreCMC need to be able to distribute or reuse documentation that libreCMC should be providing.

The libreCMC has had a lack of documentation for most of the project's life due to lack of time and upstream docs being non-free (CC-BY-NC-SA) or tainted with documentation from the same / similar source. libreCMC documentation needs to be cleanly written and can't be tainted with non-free documentation (all docs should be licensed CC-BY-SA). The reason this is a concern is because vendors who sell devices with libreCMC need to be able to distribute or reuse documentation that libreCMC should be providing.

I would like to contribute some docs, what is the most needed docs?

I would like to contribute some docs, what is the most needed docs?

@jonasbits2, a good start is by identifying the things that you find confusing. For example, here's a question that I didn't understand until @jxself explained it to me repeatedly:

What is the difference between "factory" and "sysupgrade" images? When would I use one over the other? I'm still trying to figure out how to express an answer...

@jonasbits2, a good start is by identifying the things that you find confusing. For example, here's a question that I didn't understand until @jxself explained it to me repeatedly: What is the difference between "factory" and "sysupgrade" images? When would I use one over the other? I'm still trying to figure out how to express an answer...
pi31415 commented 6 years ago

Two questions:

Two questions: - How does one edit the wiki? - Is there any reason text can't be copied and pasted from docs like <https://lede-project.org/docs/user-guide/introduction_to_lede_configuration> where it is labeled "CC Attribution-Share Alike 4.0 International"? It would only require about 4 minor edits to convert from LEDE to librecmc.
RISCI_ATOM commented 6 years ago
Collaborator

1) Fork and make a pull request against https://gogs.librecmc.org/libreCMC/libreCMC-wiki

2) The concern is that some LEDE documentation is still tainted with stuff pulled from the OpenWRT wiki (which is licensed CC-NC-BY). I don't want to run the risk of tainting libreCMC with it.

1) Fork and make a pull request against https://gogs.librecmc.org/libreCMC/libreCMC-wiki 2) The concern is that some LEDE documentation is still tainted with stuff pulled from the OpenWRT wiki (which is licensed CC-NC-BY). I don't want to run the risk of tainting libreCMC with it.
txt.file commented 4 years ago

As of today openwrt.org shows me that it is licensed under CC-BY-SA 4.0.

As of today openwrt.org shows me that it is licensed under CC-BY-SA 4.0.
lenzj commented 3 years ago

I was considering contributing to documentation regarding supported hardware. It seems that the current information is quite dated and doesn't align with what is available in the releases?

I currently use a WNDR3800 and was researching whether there are faster routers compatible with LibreCMC and ended up buying a used TP-Link WDR4300. Somehow I missed that there are Archer-C7 releases available which probably would have been a better choice. Or are those models not in the "supported" category?

Any suggestions on how I could tackle documentation updates to make the choices easier for new users of LibreCMC or existing users looking to upgrade?

I was considering contributing to documentation regarding [supported hardware](https://gogs.librecmc.org/libreCMC/libreCMC/src/LTS/docs/Supported_Hardware.md). It seems that the current information is quite dated and doesn't align with what is available in the [releases](https://librecmc.org/librecmc/downloads/snapshots/v1.5.1/targets/ath79/generic/)? I currently use a WNDR3800 and was researching whether there are faster routers compatible with LibreCMC and ended up buying a used TP-Link WDR4300. Somehow I missed that there are Archer-C7 releases available which probably would have been a better choice. Or are those models not in the "supported" category? Any suggestions on how I could tackle documentation updates to make the choices easier for new users of LibreCMC or existing users looking to upgrade?
RISCI_ATOM commented 3 years ago
Collaborator

Sadly, the supported hardware list is (mostly) up-to-date. The project is not able to support all of the devices that have images available, for various reasons. In order to get official support from the project, a device must meet the following requirements:

  • libreCMC must be installable from stock firmware, preferably from the provided web-ui.

  • The device can't contain hardware that requires the usage of non-free drivers or blobs.

  • The device's model line can't contain revisions that would not work with libreCMC (ex. v1 works, but v2 or v3 can't be supported). This requirement makes it less confusing and reduces the risk that an unsupported device would purchased.

  • The project must be able to obtain the device for testing. If an issue pops up, then we must be able to replicate it on real hardware.

The devices that are not on the supported list can't meet these requirements, don't have full support, have not been tested or are difficult to obtain.

I currently use a WNDR3800 and was researching whether there are faster routers compatible with LibreCMC and ended up buying a used TP-Link WDR4300. Somehow I missed that there are Archer-C7 releases available which probably would have been a better choice. Or are those models not in the "supported" category?

The Archer C7 v1/v2 is a good example of this issue. The reason that the project provides images is because the non-free wifi module can be replaced. If we added it to the supported list, people might buy it and expect it to work out of the box w/o any modifications.

Any suggestions on how I could tackle documentation updates to make the choices easier for new users of LibreCMC or existing users looking to upgrade?

The main challenge is that we need to make the distinction about what is supported (out of the box) and what could be supported if someone is willing to put the work into it; we need to do it without endorsing devices that contain non-free hardware out of the box.

Sadly, the supported hardware list is (mostly) up-to-date. The project is not able to support all of the devices that have images available, for various reasons. In order to get official support from the project, a device must meet the following requirements: * libreCMC must be installable from stock firmware, preferably from the provided web-ui. * The device can't contain hardware that requires the usage of non-free drivers or blobs. * The device's model line can't contain revisions that would not work with libreCMC (ex. v1 works, but v2 or v3 can't be supported). This requirement makes it less confusing and reduces the risk that an unsupported device would purchased. * The project must be able to obtain the device for testing. If an issue pops up, then we must be able to replicate it on real hardware. The devices that are not on the supported list can't meet these requirements, don't have full support, have not been tested or are difficult to obtain. > I currently use a WNDR3800 and was researching whether there are faster routers compatible with LibreCMC and ended up buying a used TP-Link WDR4300. Somehow I missed that there are Archer-C7 releases available which probably would have been a better choice. Or are those models not in the "supported" category? The Archer C7 v1/v2 is a good example of this issue. The reason that the project provides images is because the non-free wifi module can be replaced. If we added it to the supported list, people might buy it and expect it to work out of the box w/o any modifications. > Any suggestions on how I could tackle documentation updates to make the choices easier for new users of LibreCMC or existing users looking to upgrade? The main challenge is that we need to make the distinction about what is supported (out of the box) and what could be supported if someone is willing to put the work into it; we need to do it without endorsing devices that contain non-free hardware out of the box.
lenzj commented 3 years ago

I made a mock up of a supported hardware page here. Before I put more work into this though I wanted to get feedback regarding the formatting style and type of content on the page.

If we can agree on a format I can go ahead and add in content on other devices that are in the releases folder and solicit for further feedback before submitting a pull request. It looks like many of those would go into the "unsupported" category.

By the way, per the comment from @txt.file above can you confirm whether we are now able to leverage documentation from openwrt.org?

I made a mock up of a supported hardware page [here](https://gogs.librecmc.org/lenzj/libreCMC/src/LTS/docs/Supported_Hardware.md). Before I put more work into this though I wanted to get feedback regarding the formatting style and type of content on the page. If we can agree on a format I can go ahead and add in content on other devices that are in the [releases folder](https://librecmc.org/librecmc/downloads/snapshots/v1.5.2/targets/ath79/generic/) and solicit for further feedback before submitting a pull request. It looks like many of those would go into the "unsupported" category. By the way, per the comment from @txt.file above can you confirm whether we are now able to leverage documentation from openwrt.org?
lenzj commented 3 years ago

Bump. Any interest in the updates I proposed?

Bump. Any interest in the updates I proposed?

The most significant obstacle is that we have to differentiate between what is supported "out of the box" and what might be supported. Cre: Backrooms game

The most significant obstacle is that we have to differentiate between what is supported "out of the box" and what might be supported. Cre: [Backrooms game](https://backroomsgame.io)
GNUtoo commented 2 weeks ago

The Archer C7 v1/v2 is a good example of this issue. The reason that the project provides images is because the non-free wifi module can be replaced. If we added it to the supported list, people might buy it and expect it to work out of the box w/o any modifications.

A solution for that could be to not support the "Archer C7 v1/v2" but instead to support a "modified Archer C7 v1/v2 with the nonfree WiFi module replaced by a free one" or find some good enough wording that make sure people do get that they need to modify the device in the device name itself.

Having a hardware vendor that does exactly that (like the ones that apply for RYF) would also help so that people could also get one already modified from such vendor (possibly under anohter name like Technoethical / ThinkPenguin C7 or something like that).

What is lacking is also information on how to practically speaking add support for devices.

If a device meet all the above criteria and that it is already supported by OpenWRT, how to add it is not clear. Maybe I missed it though.

As I see it, several targets met these criteria and could be added with a bit of work by (ideally new contributors that are interested in that).

For instance various emulators targets are easy to add. For instance qemu x86 (with the qemu-pc machine), qemu 32bit arm or 64bit arm can also be added. One thing that could be required there is to have the contributor write the corresponding documentation to have the (emulated) target officially supported.

I think this is useful as it enables to easily test LibreCMC and can also help working on it. It could also be useful to do automatic testing and catch some of the potential issues first.

Then looking at the list of devices supported by OpenWRT gives many more potential targets. For instance Olimex manufactures hardware and keep the same models around for a very long time. So it might be possible to find single board computers that can be added relatively easily once research is done to identify if there can be issues for testing (like Ethernet PHY changing over time). As part of my work on Parabola we already asked for boards to Olimex, and so it might even be possible to obtain multiple variants of a given single-board-computer if they are still available.

While many of these don't have WiFi by default or mPCIe/PCIe and that USB WiFi is not ideal (ath9k_htc probably still has a limit on the number of client when in access point mode), there are other use cases that don't need WiFi like using it to do PPPOE<->Ethernet. And here having images for emulators could also enable people to promote more such use cases as people can just look what they can do with LibreCMC easily.

Finally having a path to add newer targets might also make it possible for people to identify potential targets and add support for them upstream so they could then land in LibreCMC and add support there.

Several ARM single board computers have mPCIe or even PCIe slots, so by identifying a combination that is easy to support, and doing the missing work, it might also be possible to support these. And sometimes it's also possible to convince the manufacturers of single board computers to also sell some additional hardware with it to customers to be compatible with specific distributions or use cases. An example here is Olimex and the Freedombox project, but RYF vendors might be willing to do part of the support and make sure that the hardware is already assembled and so on.

Denis.

> The Archer C7 v1/v2 is a good example of this issue. The reason that the project provides images is because the non-free wifi module can be replaced. If we added it to the supported list, people might buy it and expect it to work out of the box w/o any modifications. A solution for that could be to not support the "Archer C7 v1/v2" but instead to support a "modified Archer C7 v1/v2 with the nonfree WiFi module replaced by a free one" or find some good enough wording that make sure people do get that they need to modify the device in the device name itself. Having a hardware vendor that does exactly that (like the ones that apply for RYF) would also help so that people could also get one already modified from such vendor (possibly under anohter name like Technoethical / ThinkPenguin C7 or something like that). What is lacking is also information on how to practically speaking add support for devices. If a device meet all the above criteria and that it is already supported by OpenWRT, how to add it is not clear. Maybe I missed it though. As I see it, several targets met these criteria and could be added with a bit of work by (ideally new contributors that are interested in that). For instance various emulators targets are easy to add. For instance qemu x86 (with the qemu-pc machine), qemu 32bit arm or 64bit arm can also be added. One thing that could be required there is to have the contributor write the corresponding documentation to have the (emulated) target officially supported. I think this is useful as it enables to easily test LibreCMC and can also help working on it. It could also be useful to do automatic testing and catch some of the potential issues first. Then looking at the list of devices supported by OpenWRT gives many more potential targets. For instance Olimex manufactures hardware and keep the same models around for a very long time. So it might be possible to find single board computers that can be added relatively easily once research is done to identify if there can be issues for testing (like Ethernet PHY changing over time). As part of my work on Parabola we already asked for boards to Olimex, and so it might even be possible to obtain multiple variants of a given single-board-computer if they are still available. While many of these don't have WiFi by default or mPCIe/PCIe and that USB WiFi is not ideal (ath9k_htc probably still has a limit on the number of client when in access point mode), there are other use cases that don't need WiFi like using it to do PPPOE<->Ethernet. And here having images for emulators could also enable people to promote more such use cases as people can just look what they can do with LibreCMC easily. Finally having a path to add newer targets might also make it possible for people to identify potential targets and add support for them upstream so they could then land in LibreCMC and add support there. Several ARM single board computers have mPCIe or even PCIe slots, so by identifying a combination that is easy to support, and doing the missing work, it might also be possible to support these. And sometimes it's also possible to convince the manufacturers of single board computers to also sell some additional hardware with it to customers to be compatible with specific distributions or use cases. An example here is Olimex and the Freedombox project, but RYF vendors might be willing to do part of the support and make sure that the hardware is already assembled and so on. Denis.
Sign in to join this conversation.
Loading...
Cancel
Save
There is no content yet.