Changelog

I’m documenting what I’ve done with the docs here for SFL. We will delete this page once the new docs get accepted for docs.jami.net

• added “How to contribute to this documentation”

• refactored build guide (old build page should still be checked to make sure I didn’t remove anything important)

• rewrote introduction

• organized everything into a series of chapters like “General”, “Technical Reference”, etc (every page can be accessed at any time through the sidebar)

• removed handwritten tables of contents in pages and replaced them with autogenerated TOCs

• fixed grammer and spelling in FAQ; added all questions from the old Ring FAQ that hadn’t been added yet; added everything from the website FAQ; combined some similar questions

• Old links were out of date and not very useful, but just in case, here they are:

  • https://web.archive.org/web/20181226012503/https://ring.cx/en/documentation/faq

  • https://web.archive.org/web/20181226012541/https://ring.cx/en/about/privacy-and-anonymity

  • https://web.archive.org/web/20180224163130/https://ring.cx/en/about/practical

  • old wiki link no longer works: https://tuleap.ring.cx/plugins/mediawiki/wiki/ring/index.php?title=Special:AllPages

• added some new questions to the FAQ

• added all relevant questions from the jami.net FAQ to this FAQ (we should just have one document)

• made all headlines in the FAQ questions

• uploads/media are now located in the same directory as the document that refers to them

  • if documents from multiple chapters refer to a file, the file can go in the media/ directory

• renamed guides to “How to…” based on this advice: https://documentation.divio.com/how-to-guides/

• Changed filenames to lowercase-with-hyphens, and use .md for markdown and .txt for reStructuredText following this: https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html

  • all documents should only have one h1, which becomes the title of the document

• Moved most of the audio/video stuff into a separate “troubleshooting” page; IMO these types of troubleshooting questions aren’t meant for the FAQ and they make it look bad. Some of them should be deleted alltogether, for instance questions asking the location of a setting which is just sitting there in the “general settings” page.

• deleted UI and UX development page because it was useless and completely outdated and all of the image links were broken (it can be remade later if needed)

• deleted many broken image/file links from other pages

• moved many old pages into extra/ where we can start culling or reintegrating them. plenty are just old drafts that can probably be deleted

Notes

• FAQ is pretty large. I don’t know if parts of it should be moved to other pages

• the “General” chapter should remain the top priority; we should be open to debate about which things to include or exclude, and we should strive to keep the chapter complete and correct. 99% of users won’t read the other chapters. The first chapter is still an entry point, so it counts as marketing as well as documentation.

• Linking guide: from the “General” chapter, only link to other documents in the same chapter, except for the technical overview, which can link to the technical reference. For instance, in the FAQ, link to the name server heading of the Technical Overview, but in the Technical Overview, you can link to the name server page of the technical reference (there are a few exceptions, like linking to “How to contribute”)

• linking to other parts of the documentation summary: for whole documents, use

:doc:`link title <relative-path-no-file-extension>`

for headings in documents, use

:ref:`link title <full/path/to-doc-no-file-extension:headline title with spaces (case sensitive)>`

There are many examples in the FAQ. Please test your links before submitting patches. TODO: add this information to the contribution guide.

• markdown works fine but RST is better because then we can generate a pdf of the documentation

TODO

• add notes about cross-referencing documents in the contribution guide

• make a more general “contribute” page (like https://jami.net/contribute/ )

• edit the bug report guide

• go through the old build instructions page and make sure the new chapter isn’t missing something

• organize the technical reference

• delete some pages from the technical reference or the “Extra” chapter

• Improve PDF generation

• Internationalization

• other TODOs listed throughout the documentation

• Finish the Technical Overview in the General chapter (we’re about halfway done)

• Finish going through the FAQ (I need to check the “Advanced” section for spelling and grammar, and there may be some redundancy)

• Finish the “Feature requests” and “Troubleshooting” pages

• Someone need to write the DHTproxy guide (one user has volunteered to give us a checklist after he does it)