Delete TESTING.md #3478
Delete TESTING.md #3478
Conversation
Delete page because an exact duplicate exists in the Handbook
|
I have one concern about deleting all these docs from mbed OS. Now when we make a change (or a partner or a community member) to mbed OS that requires a documentation update, we would have to sync it up across two repos. The benefit of having these documents in mbed OS means the code change can come in alongside the documentation changes. How is the Handbook synced with mbed OS currently? Is it a manual process? |
|
I'd recommend the following moving forward for mbed OS docs (feel free to suggest changes):
Thoughts @sg-, @iriark01, @AnotherButler ? |
The handbook is published from the handbook repo. The docs here are nothing more than stale md files. The docs will move back into mbed OS when we get a docs engine that support multiple table of contents from a single repo. What seems like a small technical challenge - it has kept us from docs being in one location. I'd prefer that all link to help are pointing at published docs, not readme files rendered by github. |
I agree, though shouldn't we endeavor to freshen up the stale md files? Especially if there are deeply technical details that don't belong in the main Handbook (having trouble thinking of a good example at the moment though, so maybe this isn't a valid concern).
Totally fine with linking to the docs site from GitHub for documentation, no worries there. The only thing I'm concerned about is what I described above, meaning if someone makes a change in the code base that requires a documentation change, they'd have to go update a separate repo with this change, and keep the two repos in sync. We don't really do a good job of this anyway at the moment, even though we still have docs in this repo (see this change: #3469), but we could always get better at it if we placed a larger emphasis on it. In my opinion, separating the docs from the code would make this more difficult. If however you don't share this concern or we just need to go this route for the time being, than that's fine too. Just thought I'd bring up this point of view first before we start merging these changes. |
This very much concerns me but getting contributions to docs that are not published is worse IMO. Until we have the docs build engine worked out I'd prefer the docs directory here to just have links to where handbook or api docs should be modified. There is a good workflow of making changes to a branch of the docs which then gets rendered live. This way 5.1 / 5.2 / 5.3 can all live a long prosperous docs life. As pointed out - API docs in code aren't well versioned at the moment (to my knowledge). Regardless - I don't know if docs and API docs in the same repo fixes this. My guess is it doesn't until the docs are a snapshot or pdf like rendering of a build. Referencing URLs will always lead to this problem I think. Looks like in 5.3 we reduced the scope of API docs but this is what I was referring to. https://docs.mbed.com/docs/mbed-os-api-reference/en/5.2/APIs/io/DigitalIn/ and https://docs.mbed.com/docs/mbed-os-api/en/mbed-os-5.2/api/classmbed_1_1DigitalIn.html The patch level releases are not respected but that would be a lot of maintenance. |
Hopefully I'm not beating a dead horse here, just wanted to reiterate one comment in response to this. We could have the docs that live in mbed-os (the ones that need to be versioned along with the code) get submitted as a PR to the Handbook repo via the automated release script. That way it'd stay in sync with the releases. However, if this is less useful than I'm assuming it is then we can always just make these changes directly to the Handbook repo. We just need to be proactive in that case. I think I'm beginning to grasp a bit more of the advantages of having some of the docs outside of mbed OS. Especially if some of those docs touch parts of the mbed ecosystem that are outside of this repository. So I don't want to hold up these PRs up any more if that's the case. EDIT:
100% agree! |
If you're volunteering to make this happen - lets do it! Need to mirror both the API docs and handbook and we can move them in docs/ https://github.com/ARMmbed/Handbook Just make sure @iriark01 is on board and that we end up with one set of docs to maintain. |
|
Had quick sync with @AnotherButler and many more things are becoming clearer to me! Ok, so my final suggestion would be to keep the Handbook out of mbed OS for now, since it touches all parts of the mbed ecosystem, not just what's contained within the mbed-os repo (mbed CLI, online compiler, etc). However, the mbed OS API Docs could/should essentially be a copy-paste from the mbed-os/docs folder. Does that sound about right? |
|
I don't like removing docs from sources :/ I think all the docs should live in sources so they are easy to find when you need them, agreed that out of date docs are worse than no docs, but to be fair there is a mixture of up to date and outdated docs in both handbook and mbed-os. Could we have docs for each project in the project repo and the handbook could pull or link with the each project repo. It would make it easier to keep the docs up to date and easier to enforce if it all can be committed in one PR. |
|
I also like having docs with sources, to be able to read them offline while developing plus updating them when repo changes. To summarize:
|
Delete page because an exact duplicate exists in the Handbook