Documentation Updates

[jeremymturner]

• Created a README.md in the root to display on the main repo page with links to documentation
• Converted hellov2.pdf to markdown, added images
• Converted other text files into markdown with formatting
• Moved all documentation into the doc folder

[afarhan]

With the V3, I have moved the manual to the wiki (www.sbitx.net) to make it easier and more upto date. Should we redo the README and do away with the markdown manual? I am in two minds: we need the markdown for offline usage and we need the web version for the latest. Is it possible that we get a version of the web synced up each time there is a change on sbitx.net?

[n1ai]

My thoughts/opinions:

• You should use whatever format you find convenient for end-user documents even if this means abandoning the user-facing markdown documents in this PR (again, just my thoughts)
• The sbitx.net document ( link ) is well done and easy to read, but it's not clear how other people can edit it or even suggest improvements, can you explain?
• Technical support documents should stay in this repo but not be in the top level directory, they should be moved to their own directory and this PR puts them in ./docs which I think is a good idea
• It is better to have technical support documents in markdown (.md) format rather than text (.txt) format
• Also having a nicely formated README.md in the top-level directory is a good thing
• I think it's a good idea to use 'print to PDF' to create a PDF version of the sbitx.net document and check it in here, so we have a revision-controlled and easily accessed version here as well as in sbitx.net

Please advise.

[jeremymturner]

My my changes were twofold: 1) make it easier for users to contribute changes to documentation (pdf->md conversion), and 2) move to a separate docs folder to not mix up code and docs.I thought that there could also be pandoc or similar so that a PDF copy would be available for those who want PDF. Although I find markdown very readable as a text format too, and most other code contributors would. Users, maybe not as much.I apologize, I haven’t checked out the sbitx.net site yet. User documentation versus contributor documentation might mean some docs end up in the repo, some on a different site. But if you make it easier for people to contribute clarifications, there’s probably less that people will email the email list.Thanks and 73, Jeremy / N0AWOn Jan 19, 2024, at 10:13, n1ai ***@***.***> wrote: My thoughts: You should use whatever format you find convenient for end-user documents even if this means abandoning the user-facing markdown documents in this PR (again, just my thoughts) The sbitx.net document ( link ) is well done and easy to read, but it's not clear how other people can edit it or even suggest improvements, can you explain? Technical support documents should stay in this repo but not be in the top level directory, they should be moved to their own directory and this PR puts them in ./docs which I think is a good idea It is better to have technical support documents in markdown (.md) format rather than text (.txt) format Also having a nicely formated README.md in the top-level directory is a good thing Please advise. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you authored the thread.Message ID: ***@***.***>